Errors

Failed merchant API requests return JSON with success: false, a human-readable error, and a machine code.

Common codes (API key auth)

Session-only dashboard errors (for example EMAIL_NOT_VERIFIED) are returned when using a Clerk session on dashboard routes — not when calling the merchant HTTP API with an API key. See Dashboard vs API.

Example

Code
{
  "success": false,
  "error": "API key missing required scope (read:orders)",
  "code": "FORBIDDEN"
}

Include an optional x-cid header on requests so support can trace audit logs.

Next steps

• Authentication — headers and base URL
• Rate limits — backoff guidance
• API Reference — per-operation responses