Errors and limits
Error shape
Errors Model Gateway raises are JSON with one field:
{"error": "spend grant limit would be exceeded"}
401is always{"error":"unauthorized"}and403is always{"error":"forbidden"}. Neither says why.- Every
5xx,503included, is{"error":"internal error"}; details are kept out of responses. - Other
4xxmessages are written for people and may change. There are no error codes.
curl -sS https://gqbzygqa4dd3t54xnb2fg5wcou0pitmm.lambda-url.us-east-1.on.aws/v1/model-gateway/custom-adapters | grep -Fx '{"error":"unauthorized"}'
Some errors are not JSON. They come from request parsing, which happens
only after Model Gateway has accepted your credential (a request without one
gets 401 whatever its body), and are plain text:
| Status | Cause | Example body |
|---|---|---|
400 | A path id is not a UUID, or the body is not valid JSON | Invalid URL: Cannot parse `credential_id` with value `not-a-uuid`: ... |
413 | Body larger than 2 MiB | Failed to buffer the request body: length limit exceeded |
415 | Body sent without Content-Type: application/json | Expected request with `Content-Type: application/json` |
422 | Body is JSON but a required field is missing or has the wrong type | Failed to deserialize the JSON body into the target type: missing field `api_key` ... |
Status codes
| Status | Meaning |
|---|---|
200, 201, 204 | Done. Creating returns 201; deleting and revoking return 204. |
400 | A field breaks a rule: see the tables in API examples. Also a credential for a provider that is neither built in nor one of the person’s custom adapters, a model call that names no spend grant, or one on a custom-provider credential created before credentials carried a destination (2026-11-14). |
401 | No token, a token ChirpAuth doesn’t verify, or a missing or invalid x-user-id. |
403 | A person’s sign-in token; a missing or malformed x-granite-grant; a Granite grant Granite doesn’t approve; a model call on a spend grant Granite doesn’t approve for the calling agent, or one revoked in Granite. |
404 | No such credential or adapter for this person, including a model call on a spend grant whose credential was deleted. Another person’s records read as 404 too. |
409 | A custom adapter with that name exists, or a spend grant has no units left. |
413, 415, 422 | Parsing errors; see above. |
500 | Something failed inside Model Gateway. |
503 | Granite could not be reached. Retry later. |
Rate limits
Model Gateway sets no rate limits or quotas of its own.
Size limits
| Limit | Value |
|---|---|
| Request body | 2 MiB |
x-user-id | 128 characters |
provider, label, adapter name | 128 characters |
api_key | 8 to 4096 characters |