​
Error Format

All API errors return a JSON object with a message array: 
{
  "message": ["Human-readable error description"]
}
The message field is always an array, even for single errors.

​
HTTP Status Codes

CodeMeaningWhen
200SuccessRequest completed successfully
201CreatedResource created (cart, order)
204No ContentResource deleted
400Bad RequestValidation error, business logic error, or expired token
401UnauthorizedMissing x-cc-app or User-Agent header
404Not FoundEndpoint doesn’t exist
500Server ErrorInternal timeout or service failure

​
Common Errors

​
Authentication

Error MessageCauseResolution
"no Authorization token was found"Token expired or missingCall POST /session for a new token
"no x-cc-app was found"Missing x-cc-app headerAdd your partner app ID header
"Unauthorized"Missing User-Agent headerEnsure User-Agent header is set

​
Cart Operations

Error MessageCauseResolution
"Error, insufficient inventory"Cards no longer availableRefresh inventory and try different cards

​
Checkout

Error MessageCauseResolution
"Insufficient funds"Payment failedCheck payment details or use different method

​
Wallet

Error MessageCauseResolution
"OVER_THE_LIMIT"Viewed 10+ cards in 24hComplete wallet verification flow
"SENDS_EXHAUSTED"Max verification sends reachedWait for limit reset
"SUBMISSIONS_EXHAUSTED"Max code attempts reachedWait for limit reset

​
Retry Strategy

​
Safe to Retry (Idempotent)

  • All GET requests
  • POST /session (creates or returns existing)
  • POST /carts (creates or returns existing)

​
Do NOT Retry

  • POST /orders — may create duplicate orders
  • PUT /orders/:id — may process payment twice
async function apiCall(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const message = error.response?.data?.message?.[0] || '';

      // Token expired — refresh and retry
      if (message === 'no Authorization token was found') {
        await refreshSession();
        continue;
      }

      // Server error — wait and retry
      if (error.response?.status === 500 && attempt < maxRetries - 1) {
        await sleep(1000 * (attempt + 1));
        continue;
      }

      // Business logic error — don't retry
      throw error;
    }
  }
}

​
Timeouts

The API has internal timeouts of 50-90 seconds for most operations. If a downstream service doesn’t respond, you’ll receive a 500 with no body. Recommended client timeout: 60 seconds for most endpoints, 120 seconds for checkout.