Documentation

Error reference

Every non-2xx response from the CardVault Identify API shares one predictable shape. Discriminate on ok — false means something went wrong before we could return a result.

Back to API docs

The ApiErrorBody shape

{
  "ok": false,
  "requestId": "req_3b7c...",
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "frontImageUrl is required.",
    "param": "frontImageUrl",
    "docsUrl": "https://aicardvault.io/docs/errors"
  }
}

error.type

One of the six error types below — the stable value to branch your error handling on.

error.code

A finer-grained machine-readable code within that type (e.g. missing_field, invalid_key) — useful for logging, not required for branching.

error.message

Human-readable detail, safe to log but not guaranteed stable across versions — don't pattern-match on it.

error.param

Present on invalid_request_error — names the specific request field that failed validation.

Error types

Type	Likely HTTP status	Description
`authentication_error`	401	The Authorization header is missing, malformed, or the API key is invalid or revoked. Check that you're sending Authorization: Bearer <key> with a live key from /dashboard/keys.
`invalid_request_error`	400	The request body failed validation — a required field is missing (e.g. frontImageUrl), a field has the wrong type, or an enum value (like category) isn't recognized. The error's param field names the offending field when applicable.
`rate_limit_error`	429	You've exceeded your plan's requests-per-second ceiling (5/s Free, 25/s Pro, 100/s Scale). Back off and retry with exponential backoff, or upgrade your plan for more headroom.
`quota_error`	429	You've used your full monthly identify allotment for the current billing period. Free plan requests pause until next month; paid plans either bill overage or need an upgrade, depending on your plan.
`upstream_error`	502	An internal recognition provider or pipeline stage failed transiently. This is rare — by design, most upstream faults degrade to an honest 200 miss (needsReview:true) rather than surfacing as an error. Safe to retry.
`api_error`	500	An unexpected server-side failure not covered by another type. If this persists across retries, contact support with the requestId.

A hard-to-identify card is never an error

An honest miss — needsReview: true, card: null — is a normal 200 OK from /api/v1/identify, not one of the error types on this page. Only request problems, auth failures, and infrastructure faults produce an ApiErrorBody.