Problem catalog - Cortex Docs

Every Cortex failure carries a code and a type. The type is a URL that resolves to a page on this site, so an error message can point at its own explanation. The base is https://docs.cortex.foundation/problems. Each code has a page at /problems/{code}, and the path is the snake_case code — rate_limited, not rate-limited.

Start with the status

Status	Usually means	Where to look
400 / 422	The request was malformed or the resource forbids it	`validation_failed`, `bad_request`, `invalid_state`
401 / 403	Sign-in, permission, or plan	`unauthenticated`, `invalid_credential`, `forbidden`, `entitlement_required`
404 / 409 / 410	The resource moved, changed, or was deleted	`not_found`, `conflict`, `gone`
413 / 415	The payload is too big or the wrong type	`payload_too_large`, `unsupported_media_type`
429	Too fast, or out of plan quota	`rate_limited`, `quota_exceeded`, `concurrency_limit_reached`
500–504	Our side	`internal`, `service_unavailable`, `no_capacity`, `upstream_failure`, `upstream_timeout`

Retryable: yes means the same request can succeed later. Retryable: no means retrying changes nothing — the request, the plan, or the state has to change first.

All codes

Code	HTTP	Retryable
`validation_failed`	422	no
`bad_request`	400	no
`idempotency_key_reuse`	400	no
`payload_too_large`	413	no
`unsupported_media_type`	415	no
`unauthenticated`	401	no
`invalid_credential`	401	no
`forbidden`	403	no
`entitlement_required`	403	no
`safety_intervention`	403	no
`content_policy`	403	no
`jurisdiction_restricted`	403	no
`not_found`	404	no
`conflict`	409	yes
`gone`	410	no
`invalid_state`	422	no
`quota_exceeded`	429	no
`rate_limited`	429	yes
`concurrency_limit_reached`	429	no
`internal`	500	yes
`upstream_failure`	502	yes
`service_unavailable`	503	yes
`no_capacity`	503	yes
`upstream_timeout`	504	yes

Two 429s that mean different things

rate_limited is transport throttling — you are sending requests too fast, and waiting fixes it. quota_exceeded is a plan window running out — waiting for the reset or changing plan fixes it. Read the code, not the status.

Errors - the shape of a problem document and which fields to render.
Platform API - why there is no public inference API to raise these codes against yet.
Troubleshooting - what a message in the product means.