Errors — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Errors

SupaNexus API (`/v1/*`) uses **[OpenRouter-compatible errors](https://openrouter.ai/docs/api/reference/errors-and-debugging)**: `error.code` is a **number** equal to the HTTP status.

## Error JSON format

```json
{
  "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:

```json
{
  "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](./authentication.md#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:

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

See [Messages](./messages.md) 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](./streaming.md).

## Related

- [Rate Limits & Quotas](./rate-limits-and-quotas.md)
- [Authentication](./authentication.md)