Errors and limits
Handle authentication, validation, locale, filter, cursor, and preview failures.
Branch on HTTP status and stable structured codes, never message text. REST and GraphQL use different error envelopes.
REST errors
{ "error": "Unknown type: missing" }Use the HTTP status to classify REST failures.
GraphQL errors
{
"errors": [
{
"message": "Locale is not available",
"extensions": {
"code": "NOT_FOUND",
"http": { "status": 404 }
}
}
]
}GraphQL clients may expose transport status differently. Read errors[].extensions.code and errors[].extensions.http.status when available.
Error map
| Condition | HTTP status | Structured code |
|---|---|---|
| Missing or invalid delivery key | 401 | Not guaranteed for REST |
| Invalid Preview Bearer | 401 | INVALID_TOKEN |
| Expired or revoked Preview Bearer | 401 | EXPIRED_OR_REVOKED |
| Missing or disallowed Backend scope | 403 | Not guaranteed for REST |
| Disabled Preview target or invalid context | 403 | TARGET_DISABLED, CONTEXT_INVALID, or ACCESS_REVOKED |
| Delivery key plus Preview Bearer | 400 | AMBIGUOUS_CREDENTIALS |
| Unknown locale | 400 | BAD_USER_INPUT |
| Invalid filter, sort, or cursor | 400 | BAD_USER_INPUT |
| Preview locale outside authorization | 404 | NOT_FOUND |
| Unknown REST type, Vocabulary, or ID | 404 | REST {error} only |
Preview exchange has its own { "error": { "code", "message" } } envelope. Malformed input is 400; invalid, replayed, expired, or revoked codes are 401; disabled targets and invalid context are 403.
Verified ceilings
| Constraint | Value |
|---|---|
| GraphQL depth | 12 |
| Default page size | 25 |
| Page-size cap | 100 |
| Content sort plans | 3 |
| Filter predicates | 32 |
| Filter depth | 6 |
OR breadth |
16 |
| Relation hops in filters | 3 |
| Component depth in filters | 5 |
Production GraphQL introspection is disabled. Jetrepo does not publish a Delivery API rate limit, response-size limit, cursor lifetime, SLA, or capacity guarantee.