# Errors and limits

Every non-2xx native API response contains an `error` object with `code`, `message`, `param` and `request_id`. Responses include `X-Request-Id`; provide it when contacting support. A `Retry-After` header indicates how long to wait when present.

```json
{"error":{"code":"insufficient_credits","message":"The balance does not cover this call.","param":null,"request_id":"example-request-id"}}
```

## Common HTTP errors

- `400 invalid_request`: malformed JSON or request body.
- `401 unauthorized`: missing, malformed, unknown or revoked key.
- `402 insufficient_credits` or `key_credit_limit_exceeded`: add balance or review the key limit.
- `403 account_locked` or `forbidden`: account lock, key scope or IP restriction.
- `404 not_found`: unknown route or object on this account.
- `409 conflict`: operation conflicts with the current state.
- `413 payload_too_large`, `415 unsupported_media_type`: reduce the body or use a JSON content type.
- `422 validation_error` or `recognition_failed`: correct the named field or load a fresh challenge.
- `429 rate_limited`, `rate_capped` or `concurrency_limit_exceeded`: respect `Retry-After` and account limits.
- `500 internal_error`, `503 maintenance`, `capacity_exhausted` or `proxy_pool_depleted`: a service-side problem; retry later when appropriate.

## Solve failures are not always HTTP errors

A successfully created solve may later end with `failed`, `cancelled` or `expired`. Inspect the solve's `error` and `retryable` fields. Possible codes include `challenge_not_loaded`, `token_not_granted`, `challenge_expired`, `proxy_error`, `vision_error`, `unsolvable_variant`, `capacity_exhausted` and `internal_error`. No charge is made for these failed solves.

## Limits

Account concurrency and requests per minute are shown in dashboard settings. New solves are capped per account and sitekey at 120 per minute. Recognition image and request size limits are listed in the Recognition API guide. Ignore fields you do not recognize: fields can be added within v1.

Canonical: https://ninetile.io/docs/errors-and-limits