# Errors and retries

Distinguish validation errors, limits, insufficient reservation balance, and model unavailability.

Source: https://shvydko.ai/en/docs/api/errors

## Read the HTTP status and detail

An error is returned with an unsuccessful HTTP status and a detail field. Validation errors may also include errors: a list of fields and messages. Do not expect answers in such a response.

### Example validation error structure

```json
{
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "body.questions",
      "message": "Questions must use supported types"
    }
  ]
}
```

> The example wording is illustrative. Handle the status and structure, rather than the exact wording of detail.

## Statuses

| HTTP | Cause | What to do |
| --- | --- | --- |
| 401 | The key is missing, unknown, or revoked | Check the server secret; do not retry with the same key |
| 402 | Insufficient available balance for a reservation in paid mode | Check the balance and active reservations |
| 403 | The organization is suspended for billing review | Check the organization's status; do not bypass it with new keys |
| 409 | The request reservation has already been finalized or expired | Check Usage; do not automatically repeat the action |
| 413 | The JSON exceeds the byte limit | Shorten the context or split the task |
| 422 | Invalid structure, model name, or rejected context | Correct the request or reduce the context |
| 429 | Per-minute limit or daily preview quota | Respect Retry-After if present; daily quotas reset at 00:00 UTC |
| 502 | The model is unavailable, returned an invalid response, or timed out | Retry within a limit and with a delay; check Usage after a lost connection |
| 503 | The model service is not connected | Check the service status later |

## Retries must be bounded

For a per-minute 429, use Retry-After and a small random delay across clients. The daily preview quota may return 429 without this header: the message will indicate a reset at 00:00 UTC.

Do not retry 401, 402, 403, 413, or 422 without addressing the cause. For network failures and 502, set a small attempt limit and a total time budget. POST /v1/systemone provides no idempotency guarantee.

The gateway does not charge credits for a request it completed with a model error. Losing the response on your client is a different situation: the server may already have completed the request successfully.

## Related documentation

- [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md)
- [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md)
- [Python over HTTP](https://shvydko.ai/en/docs-markdown/integrations/python.md)
- [JavaScript over HTTP](https://shvydko.ai/en/docs-markdown/integrations/javascript.md)