Errors

SmartAPI returns standard HTTP status codes. Error bodies follow the format of the endpoint you called: OpenAI-style on /chat/completions and /responses, Anthropic-style on /messages.

Every response — including errors — includes an X-Request-Id header. Include this value when reporting an issue so it can be traced quickly.

Status codes#

HTTP	Error type	When it happens
`400`	`invalid_request_error`	Malformed JSON or a missing `model` field.
`400`	`unsupported_protocol`	The model does not support this endpoint/protocol.
`401`	`invalid_api_key`	Missing, malformed, disabled, or expired API key.
`402`	`insufficient_quota`	Account balance is depleted.
`404`	`model_not_found`	The model is unknown or has been delisted.
`429`	`rate_limit_exceeded`	A per-key rate limit or the total quota was exceeded.
`502`	`upstream_error`	Upstream returned an error; retries across channels did not succeed.
`503`	`service_unavailable`	The model is listed but no routing channel is currently available.
`504`	`upstream_timeout`	Upstream response timed out; retries across channels did not succeed.
`500`	`internal_error`	An unexpected internal error.

OpenAI-style error body#

Returned by /chat/completions:

{
  "error": {
    "message": "Invalid, missing, disabled or expired API key.",
    "type": "invalid_api_key",
    "code": "invalid_api_key",
    "param": null
  }
}

Anthropic-style error body#

Returned by /messages:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid, missing, disabled or expired API key."
  }
}

Handling errors#

401 / 402 — Check that your key is active and your account has a positive balance. See Authentication and Billing.
404 / 400 (unsupported_protocol) — Verify the model identifier and that you are calling the correct endpoint for that model. See Models.
429 — Slow down or raise your key’s limits. See Rate Limits & Quotas.
502 / 503 / 504 — Transient upstream issues. SmartAPI retries across channels automatically; retry the request after a short backoff.