---
title: API errors
description: Handle the structured error envelope, request ids, HTTP status classes, stable codes, and retry boundaries.
species: reference
---
# API errors

Every API failure uses one envelope. Branch on `error.code`, not message text.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter.",
    "param": "sql",
    "doc_url": "https://api.supernova.ai/docs#parameter_missing",
    "request_id": "req_..."
  }
}
```

The `Request-Id` response header repeats `request_id`. Include it when contacting support. `param` appears only when one input can be named.

## Status classes

| Status | Meaning | Retry |
|---|---|---|
| `400` | Invalid input or refused capability | Change the request |
| `401` | Missing, malformed, expired, or revoked credential | Refresh or replace the credential |
| `403` | Authenticated but missing scope or role | Request appropriate access |
| `404` | Resource absent or hidden from this organization | Do not infer cross-tenant existence |
| `409` | Current state conflicts with the operation | Read current state, then decide |
| `429` | Caller, organization, or concurrency limit | Honor `Retry-After` |
| `500` | Unexpected server failure | Retry with backoff when the request is idempotent |
| `503` | Required service unavailable | Retry with backoff |

## Common codes

| Code | Meaning |
|---|---|
| `invalid_json` | Body is not valid JSON |
| `parameter_missing` | Required input is absent |
| `invalid_cursor` | Cursor did not come from the matching collection |
| `invalid_format` | Requested representation is unsupported |
| `authentication_required` | Bearer credential is absent |
| `invalid_token` | Credential failed validation |
| `insufficient_scope` | Credential lacks the endpoint scope |
| `rate_limited` | Request rate exceeded |
| `idempotency_key_reused` | Key was bound to different input |
| `query_not_found` | Query is unavailable to this organization |
| `job_not_found` | Job is unavailable to this organization |
| `catalog_not_found` | Schema or table is absent or hidden |
| `source_not_found` | Source is absent or hidden |
| `send_not_found` | Send or nested run is absent or hidden |

Resource pages list their additional codes at the operation that returns them.