Error codes

400 invalid_request_error

Your request body is malformed — missing required field, wrong type, or invalid value.

• Check that model, messages / input, and max_tokens are present and the right type.
• For tool calls, make sure tools is a JSON array (not a JSON string of an array — common copy-paste mistake).
• The type field on each message must be one of user / assistant (Anthropic) or user / system / assistant / tool (OpenAI).

401 unauthorized

The API key is missing, malformed, or doesn't match an active account.

• Confirm the key starts with cr_ and is 32+ characters.
• Use x-api-key for Claude / Anthropic requests, and Authorization: Bearer ... for Codex/OpenAI-compatible and Gemini requests. See the endpoints page.
• If the key used to work, check the dashboard — accounts with zero balance and no recent activity are sometimes suspended.

403 permission_denied

The key is valid but isn't allowed to use the requested model. Most often happens when a Claude key tries to call a GPT model by accident.

• Check the model field — all keys have access to all 12 curated models, so this is almost always a typo.

404 model_not_found

The model you sent isn't in our catalog. We proxy 12 curated models plus a long tail of others — but not every model that exists on Anthropic / OpenAI / Google's site.

• Compare your model string against the Models page.
• Watch for typos: claude-sonnet-4-6 ≠ claude-sonnet-4.6 (dot vs dash) and gpt-5.4 ≠ gpt-5.4-2025-01-01 (snapshot suffix changes monthly).
• If you need a specific snapshot / variant, email support with the model ID.

429 rate_limit_error

You sent too many requests in a short window, or hit a per-model concurrency cap.

• Default per-key limit is 60 requests / minute. For higher limits, email support.
• Exponential backoff: wait 1s, retry. Double on each failure (1s → 2s → 4s → 8s, max 30s).
• If you see this on a single concurrent request, the model itself may be rate-limited upstream. Switch to a different model in the same family (e.g. claude-sonnet-4-6 → claude-haiku-4-5).

529 overloaded_error

The upstream model is temporarily overloaded. Not your fault — the model is at capacity.

• Wait 5–15 seconds and retry. The error usually clears within a minute.
• For production, set up a fallback: try claude-sonnet-4-6 first, fall back to claude-haiku-4-5 on 529.

402 insufficient_credits

Your account balance is zero or negative.

• Top up from the dashboard. The key resumes working within seconds of payment.
• If you were charged but the balance didn't update, refresh the dashboard — webhook delivery can lag by 30s.

403 account_suspended

The account has been suspended (chargeback, ToS violation, or fraud signal).

• Email support@sparkapi.cc — we reply within 12 hours.

500 internal_server_error

Something on our side went wrong. Safe to retry after a few seconds.

• If you see the same 500 on 3+ consecutive retries, email support with the x-request-id header from the response.

502 bad_gateway

Could not reach the upstream provider. Usually transient (sub-30s).

• Retry with backoff. If it persists past a minute, check the dashboard status indicator.

504 gateway_timeout

The upstream provider took too long to respond. Default timeout is 120s.

• For very long generations, increase your client-side timeout, or switch to a streaming request and read tokens as they arrive.