# Errors (/docs/api/errors)

Error codes, HTTP statuses, the error response shape, and rate limiting.



## Response shape [#response-shape]

Every error — REST or `failed` [stream event](/docs/api/events) — uses one
public code. REST errors return:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "human-readable summary",
    "status": 422
  }
}
```

A `failed` SSE frame carries the same `code` (no `status`).

## Codes [#codes]

| Code                  | HTTP | Cause    | What to do                                                                         |
| --------------------- | ---- | -------- | ---------------------------------------------------------------------------------- |
| `invalid_request`     | 422  | You      | Bad body — wrong shape, missing `query`, bad `geography`, non-HTTPS `webhook_url`. |
| `auth_required`       | 401  | You      | Send valid `X-Orakle-API-Key`.                                                     |
| `job_not_found`       | 404  | You      | Wrong or unowned job id.                                                           |
| `rate_limited`        | 429  | You      | Honor `Retry-After`.                                                               |
| `insufficient_data`   | 422  | External | Not enough market data. Retry or refine.                                           |
| `service_unavailable` | 503  | Us       | Dispatch failure. Retry with backoff.                                              |
| `internal_error`      | 500  | Us       | Retry; contact support if persistent.                                              |

**You** — fix request. **Us** — transient. **External** — upstream limit.

## Rate limiting [#rate-limiting]

Capped per minute and per hour, by API key. Health and webhook endpoints
exempt. Exceeding returns:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Max N requests per minute.", "status": 429 } }
```

Wait at least `Retry-After` seconds before retrying. SDKs back off
automatically.