The API uses standard HTTP status codes. Any non-2xx response carries a JSON body with an error string you can log or surface to users.
Every error is a JSON object with a human-readable error field. A few responses add context fields — for example, a bad ids parameter echoes back the offending values in invalidIds.
{
"error": "Card not found"
}| Status | Name | Example body | Meaning | Retry? |
|---|---|---|---|---|
200 | OK | { "data": [ … ] } | The request succeeded. | — |
400 | Bad Request | { "error": "Invalid ids parameter. Use comma-separated UUID card ids.", "invalidIds": ["022", "abc"] } | A parameter is malformed. Fix the request and try again — don't retry as-is. | No |
401 | Unauthorized | { "error": "Missing X-API-Key header" } | The X-API-Key header is missing or the key is invalid/revoked. | No |
403 | Forbidden | { "error": "History endpoint requires trader plan or above" } | Your key is valid but your plan can't access this resource (e.g. history on Free). | No |
404 | Not Found | { "error": "Card not found" } | No card, set, or resource matches the given id. | No |
413 | Payload Too Large | { "error": "Request too large" } | The request body exceeded 10 MB. | No |
429 | Too Many Requests | { "error": "Rate limit exceeded" } | You hit your daily quota or burst limit. Read Retry-After / X-RateLimit-* headers. | Yes, with backoff |
500 | Internal Server Error | { "error": "Internal server error" } | Something went wrong on our side. | Yes, with backoff |
503 | Service Unavailable | { "error": "Database temporarily unavailable" } | A dependency is briefly unavailable. Cached data may still be served where possible. | Yes, with backoff |
Retry-After (or back off exponentially) — see rate limits.