> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.singularityapi.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.singularityapi.dev/_mcp/server.

# Errors & Rate Limits

## The error envelope

Every gateway error uses the same shape:

```json
{"error": {"message": "...", "type": "invalid_request_error", "param": null, "code": "..."}}
```

`type` is always the literal `invalid_request_error` — it does not vary by error. Branch on `code`, not `type`.

> **Note**
>
> Upstream provider errors — 4xx or 5xx responses from the model provider itself, rather than from admission — are passed through verbatim and may not match this envelope.

## Error codes

| HTTP | `code`                 | When                                                                                                 |
| ---- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request`      | Unsupported or invalid parameter, bad JSON, wrong output-limit field for the model, context overflow |
| 401  | `authentication_error` | Missing or malformed Authorization header                                                            |
| 401  | `invalid_api_key`      | Key unknown or revoked                                                                               |
| 402  | `insufficient_credit`  | Not enough credit to reserve the request's maximum possible cost                                     |
| 404  | `model_not_found`      | Unknown model or contract slug                                                                       |
| 404  | `receipt_not_found`    | Unknown receipt ID on `GET /v1/receipts/{receipt_id}`                                                |
| 409  | `request_conflict`     | Request lifecycle conflict; safe to retry                                                            |
| 413  | `request_too_large`    | Request body over the size limit                                                                     |
| 429  | `rate_limit_exceeded`  | Per-key requests-per-minute limit exceeded                                                           |
| 502  | `routing_error`        | Upstream connect or finalize failure                                                                 |
| 503  | `service_unavailable`  | Temporary platform condition                                                                         |
| 504  | `request_timeout`      | Request exceeded the \~230-second deadline                                                           |

## Retry guidance

* **Retryable**: 409, 429, 502, 503, 504. For 429, wait the number of seconds named in the message before retrying. For the others, use exponential backoff.
* **Not retryable**: 400, 401, 402, 404. Retrying without changing the request just reproduces the same error — fix the request (or, for 402, add credit) first.

## Rate limits

Rate limiting is per API key, over a fixed 60-second window. The default is **60 requests per minute per key**. This value is operator-adjustable at runtime and can change without notice or a deploy.

A rate-limited request returns 429 with a body like this:

```json
{"error": {"message": "Rate limit exceeded. Retry after 12 seconds.", "type": "invalid_request_error", "param": null, "code": "rate_limit_exceeded"}}
```

> **Warning**
>
> There's no `retry-after` header on gateway-generated 429s — the wait time is only in the `message` string. Parse it from there.

Need more throughput than the default allows? Email [support@singularityapi.dev](mailto:support@singularityapi.dev).