Errors

Replace <BASE_URL> using values from Endpoints.

SupaNexus API (/v1/*) uses OpenRouter-compatible errors: error.code is a number equal to the HTTP status.

Error JSON format

{
  "error": {
    "code": 402,
    "message": "Your account or API key has insufficient credits. Add more credits and retry the request.",
    "metadata": {}
  }
}

Field	Description
`error.code`	Integer matching the HTTP response status
`error.message`	Human-readable description
`error.metadata`	Optional extension (e.g. provider error details)

HTTP status reference

HTTP	When
400	Invalid parameters, JSON parse failure; `video_url` that is not a public http(s) URL (including data URIs, file, or vendor private schemes)
401	Missing, wrong, or expired API key
413	Request body exceeds the limit (default 64 MB, `error.code` = `request_too_large`)
402	Insufficient account or API key credits
403	Account suspended, permission denied, or missing org/project context
404	Model not found or not sellable
408	Request timeout
409	Idempotency key reused
429	Rate or usage quota exceeded (`Retry-After` may be set)
501	Embeddings / images not implemented yet
502	Service temporarily unavailable
503	Service temporarily unavailable
500	Internal service error

Account suspended (403)

When a platform user is suspended by an administrator, every /v1/* request fails after API key validation with:

{
  "error": {
    "code": 403,
    "message": "Your account has been suspended. Contact support for assistance."
  }
}

Independent of whether the key itself is still valid (non-revoked keys can still receive this error)
Access resumes immediately after unsuspension; no need to recreate keys
See Authentication — Suspended account check

Retry guidance

HTTP	Retry?	Notes
401	No	Fix API key
403	No	Contact admin if suspended; otherwise check permissions and context
402	No	Add credits or contact your administrator
404	No	Use a valid model id
408	Maybe	Reduce payload or increase client timeout
409	No	Use a new idempotency key
429	Yes	Respect `Retry-After` when present
502	Maybe	Exponential backoff, then retry
503	Maybe	Short backoff

Service auth failures

If the inference provider rejects credentials, SupaNexus typically returns 502 with message "Upstream authentication failed." rather than exposing provider details.

Anthropic `/v1/messages` errors

On POST /v1/messages, SupaNexus returns Anthropic-shaped JSON instead of OpenRouter numeric codes:

{
  "type": "error",
  "error": {"type": "authentication_error", "message": "Invalid API key"}
}

See Messages for field reference. Chat Completions continues to use the OpenRouter format above.

Streaming errors

Errors that occur before streaming starts use the JSON format above with the appropriate HTTP status. See Streaming.