Skip to documentation
DOCUMENTATIONErrors & availability
BUILD AN INTEGRATION

Errors & availability

Handle actual error codes, partial responses and source cooldowns.

Structured errors

Failures return error.code and error.message, with source and upstreamStatus when available. Record x-request-id. INVALID_INPUT is the actual input-validation code; local single-key refusal is UNAUTHORIZED, while account-backed refusal is INVALID_API_KEY. Compare codes, not human-readable messages.

429 can indicate minute quota, monthly quota, diagnostic throttling or invalid-auth admission. 503 can indicate access-store failure or temporary queue capacity. 504 identifies a request or OCR deadline. Use Retry-After when supplied; do not retry an invalid key or malformed body unchanged.

Partial snapshots

Sections are details, prices, history, listings, spotlight and image. Each reports ok, stale or unavailable. Snapshot timing belongs in sections. marketHistory embeds range/variants; listings embeds pagination/offers. They are not the focused endpoint envelopes.

An unavailable section has a null payload and an error code. Empty prices are []; empty history is an object with variants:[]; empty listings is an object with offers:[]. A missing image or featured offer can be null with status ok. A stale section retains data and its original fetchedAt after a transient source failure.

Successful OCR is preserved when catalog identification fails: identificationStatus is unavailable and identificationError explains the lookup problem. Let users edit recognized text and retry. No readable name produces not_attempted.

Bound retries

Keep one total client deadline and at most three attempts. Wait for Retry-After or use jittered backoff. If a cooldown exceeds the remaining deadline, return the failure and schedule a later read instead of retrying early. External admitted requests can debit quota even on invalid input or source failure. Preserve the last useful observation with its timestamp.

Error code catalog

400 INVALID_INPUTCheck route parameters or the JSON body.
401 INVALID_API_KEYAccount-backed key is invalid, inactive, expired or revoked.
401 UNAUTHORIZEDThe optional local single-key credential is missing or invalid.
404 NOT_FOUNDUnknown route.
404 IMAGE_NOT_AVAILABLENo source image is available for this product.
405 METHOD_NOT_ALLOWEDUse the method published for this route.
413 INVALID_INPUTRequest body exceeds the accepted byte limit.
429 RATE_LIMITEDMinute allowance exhausted; use Retry-After.
429 MONTHLY_QUOTA_EXCEEDEDMonthly allowance exhausted; retry after the next UTC month.
429 AUTH_RATE_LIMITEDAuthentication admission limit reached.
429 DIAGNOSTIC_RATE_LIMITEDUsage diagnostic rate limit reached.
500 INTERNAL_ERRORRequest failed; preserve x-request-id for support.
502 UPSTREAM_HTTP_<status>The source returned an error. Source 404 may map to API 404.
502 UPSTREAM_INVALID_RESPONSESource data failed response or identity validation.
502 UPSTREAM_RESPONSE_TOO_LARGESource or aggregate API response exceeds the byte limit.
502 UPSTREAM_NETWORK_ERRORSource transport failed.
504 UPSTREAM_TIMEOUTSource request exceeded its budget.
502 UPSTREAM_CANCELEDSource work was canceled.
503 ACCESS_STORE_UNAVAILABLEAccount access store is unavailable or misconfigured.
503 USAGE_UNAVAILABLEUsage diagnostics require account-backed mode.
503 SERVICE_BUSYService admission capacity exhausted; use Retry-After.
503 ACCESS_BUSYDatabase authorization capacity exhausted; use Retry-After.
503 UPSTREAM_BUSYSource queue is full; use Retry-After.
503 OCR_BUSYPhoto recognition queue is full; use Retry-After.
503 OCR_UNAVAILABLEPhoto recognition is unavailable.
504 OCR_TIMEOUTPhoto recognition exceeded its processing budget.
504 REQUEST_DEADLINE_EXCEEDEDTotal request deadline exceeded.
ACTUAL INPUT ERROR SHAPE
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Enter a card name or a TCGplayer product URL"
  }
}

Bounded retry example

// Run on your server. Do not log CARDCOUNTER_API_KEY.
async function readMarket(url) {
  const deadline = Date.now() + 35_000;
  for (let attempt = 0; attempt < 3; attempt++) {
    const remaining = deadline - Date.now();
    if (remaining <= 0) throw new Error('Client deadline exceeded');
    const response = await fetch(url, {
      headers: { Authorization: 'Bearer ' + process.env.CARDCOUNTER_API_KEY },
      signal: AbortSignal.timeout(remaining),
    });
    const data = await response.json();
    if (response.ok) return data;
    const header = response.headers.get('Retry-After');
    const seconds = header === null ? NaN : Number(header);
    const delay = Number.isFinite(seconds) && seconds >= 0
      ? seconds * 1000 : 250 * 2 ** attempt + Math.random() * 250;
    if (attempt === 2 || ![429, 502, 503, 504].includes(response.status)
      || delay + 100 >= deadline - Date.now()) {
      throw new Error(data.error.code + ' request=' + response.headers.get('x-request-id'));
    }
    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

Explore the wire contract.

API reference