Error Handling

Error Handling

TCG API uses standard HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": {
    "message": "Human-readable error description",
    "code": "MACHINE_READABLE_CODE"
  }
}

Status Codes

Code	Meaning
200	Success
201	Created (registration, key creation)
400	Bad request (missing params, invalid input)
401	Unauthorized (missing or invalid auth)
403	Forbidden (tier restriction)
404	Not found
409	Conflict (duplicate email)
429	Rate limit exceeded
500	Internal server error

Common Error Codes

Authentication Errors

// 401 — No API key provided
{ "error": { "message": "API key required", "code": "API_KEY_REQUIRED" } }

// 401 — Invalid key
{ "error": { "message": "Invalid or deactivated API key", "code": "INVALID_API_KEY" } }

// 401 — Session expired
{ "error": { "message": "Not authenticated", "code": "UNAUTHORIZED" } }

Rate Limit Errors

// 429 — Daily quota exceeded
{ "error": { "message": "Daily rate limit exceeded. Resets at midnight UTC.", "code": "RATE_LIMIT_EXCEEDED" } }

Tier Restriction Errors

// 403 — Endpoint requires higher tier
{ "error": { "message": "This endpoint requires a Pro subscription", "code": "TIER_REQUIRED" } }

Validation Errors

// 400 — Missing search query
{ "error": { "message": "Query parameter 'q' is required (min 2 characters)", "code": "HTTP_400" } }

// 400 — Invalid request
{ "error": { "message": "Invalid JSON", "code": "HTTP_400" } }

Handling Errors in Code

async function fetchCard(id) {
  const resp = await fetch(`https://api.tcgapi.dev/v1/cards/${id}`, {
    headers: { 'X-API-Key': API_KEY },
  });

  if (!resp.ok) {
    const err = await resp.json();
    switch (resp.status) {
      case 401: throw new Error('Invalid API key');
      case 403: throw new Error('Upgrade required: ' + err.error.message);
      case 404: return null; // Card not found
      case 429: throw new Error('Rate limited — try again tomorrow');
      default: throw new Error(err.error.message);
    }
  }

  return resp.json();
}

Retry Strategy

• 429 responses: Don’t retry until the daily reset (midnight UTC)
• 5xx responses: Retry with exponential backoff (1s, 2s, 4s)
• 4xx responses: Fix the request, don’t retry as-is