> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypastack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> One error shape. Switch on the code, never on the message.

Every failure looks the same. Switch on `error.code`, it's stable. Never parse `error.message`, it's written for humans and gets reworded freely.

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the files.delete scope.",
    "status": 403,
    "request_id": "req_8fK2mQ"
  }
}
```

Every response, success or failure, also carries an `X-Request-Id` header. Quote it if you report a problem, it maps to the exact log line.

If you meet a code you don't recognize, fall back to the HTTP status. New codes only ever get added, never repurposed, so treating an unknown code by its status is always safe.

| Status | Code                  | When                                                                                                |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`     | The body or a parameter is wrong. The response names the field in `error.param`.                    |
| 401    | `missing_key`         | No Authorization header was sent.                                                                   |
| 401    | `invalid_key`         | The key is unknown, malformed, or has been revoked.                                                 |
| 403    | `insufficient_scope`  | The key is valid but lacks the scope this endpoint needs.                                           |
| 403    | `plan_required`       | Your plan has no API access. Free plans have no keys.                                               |
| 403    | `key_limit_exceeded`  | You hold more keys than your current plan allows, usually after a downgrade. Revoke one or upgrade. |
| 403    | `quota_exceeded`      | The request would exceed your storage or link allowance.                                            |
| 404    | `not_found`           | It does not exist, or it is not yours. The two are identical on purpose.                            |
| 413    | `file_too_large`      | The file is over your plan's per-file cap.                                                          |
| 429    | `rate_limit_exceeded` | You spent your per-key budget. `Retry-After` tells you when to come back.                           |
| 500    | `internal_error`      | Something broke on Hypastack's side. Quote the `request_id` if you report it.                       |
| 503    | `server_busy`         | Hypastack is shedding load to stay up. Retry after the window.                                      |
| 503    | `service_unavailable` | A dependency is unreachable and Hypastack would rather refuse than guess. Retry shortly.            |

<Note>
  `404 not_found` is returned both when something never existed and when it belongs to someone else. That's on purpose, otherwise anyone with a key could probe ids to discover what other accounts hold.
</Note>