# Errors

Part of the HebrewCore documentation. Web: https://hc.itsbaba.com/docs#errors · Whole docs: https://hc.itsbaba.com/docs.md · Index: https://hc.itsbaba.com/llms.txt

All errors use one envelope with a stable `type`:

```json
{ "error": { "type": "rate_limited", "message": "…", "code": "rate_limited" } }
```

| Status | type | Meaning |
| --- | --- | --- |
| `400` | invalid_request | Malformed body or parameters. |
| `401` | unauthorized | Missing, invalid, or revoked API key. |
| `403` | forbidden | The key lacks a scope (`scope_required`), a Clinical call came from a browser (`server_only`), or TLS is older than 1.2 (`tls_version`). |
| `404` | not_found | No such route, or no such account term. |
| `429` | rate_limited / quota_exceeded | Burst limit or monthly character quota. |
| `500` | internal | Unexpected error. Safe to retry. |
| `502` | bad_gateway | Upstream model error. Nothing is charged. Safe to retry. |
| `503` | service_unavailable | A model feature is temporarily unavailable. |

`code` refines `type` where it helps, for example `unsupported_language` and `same_language` on protected translation, `invalid_message_format` for ICU input that does not parse, `terms_limit` on account terms, and `upstream_error` on `502`. Branch on `type` and `code`, never on `message`.