Errors
Errors
A refusal answers its status and a body with a plain code.
Example answer
HTTP/1.1 400 Bad Request{ "code": "VALIDATION_FAILED", "message": "Check the link. url: Must be a public web address.", "details": { "fields": { "url": "Must be a public web address." } }, "requestId": "18188559082372202519"}Made-up values.
A refusal answers its HTTP status and a JSON body: a plain code for your code to branch on, a sentence for people, the details when there are any, and the request’s ID for support. The status says the kind of trouble; the code says which.
| Name | Type | Description | Allowed values |
|---|---|---|---|
code | string | Stable, for code to read: the list below. | — |
message | string | For people; it can change. | — |
details | object | Every 400 carries details.fields: each field and what is wrong with it, empty when no one field is at fault. Other codes add their own facts (a 429’s window, a 413’s limit). | — |
requestId | string | The request’s ID, also in the x-request-id header. Quote it to support. | — |
An answer from Brevily’s side (a 5xx) gives its code and a general sentence only: a 500 always reads “Internal server error”, and none carries details.
Every codePermalink
The 27 codes in the API’s own catalogue, so this list grows with it: first the 18 a call can answer, then the 9 the framework keeps for things no call here does.
| Code | What it means | What to do |
|---|---|---|
400IDEMPOTENCY_ |
The Idempotency-Key is longer than 255 characters. |
Send a shorter key: a UUID does. |
400QUERY_ |
The query string is past the parser’s limits: too many parameters, or a value too long. | Send fewer parameters or shorter values. |
400VALIDATION_ |
A field, a parameter or the body is wrong, or the body is not JSON. details.fields names each field and what is wrong with it. |
Fix those fields and send it again. Sent unchanged it fails the same way. |
401UNAUTHENTICATED |
No key, a key or secret that does not match, a key revoked or expired, or a signature that does not check. A signed request’s own fault is named in details.reason. |
Check the key headers or the signature (Authentication). A revoked key stays refused: make a new one. |
403ACCESS_ |
The key is good but lacks the permission the call needs, or the organisation’s plan does not include it. | Give the key that permission in the console, or use a key that has it. |
404NOT_ |
No such record, no organisation with that code for this key, or no such call, a method a path does not take included. | Check the method, the path and the organisation’s code. |
409CONFLICT |
The record is not in a state the call can act on; the message says why. | Change what the message names first. Sent unchanged it answers the same. |
409IDEMPOTENCY_ |
The first call with this key is still running. | Wait a moment and send it again with the same key: it then answers what the first did. |
413PAYLOAD_ |
The body is over 1 MB; details.maxBytes says the limit. |
Send less in one call. |
415UNSUPPORTED_ |
A body sent as something other than JSON to a call that reads one. | Send content-type: application/json. |
422IDEMPOTENCY_ |
This key was first sent with a different request: another method, path, query or body. | Use a new key for a new request. |
429RATE_ |
Past the plan’s limit for a minute or a day. details.window says which, details.retryAfter when it frees. |
Wait Retry-After seconds (Rate limits). |
500CONFIG |
A setting on Brevily’s side is wrong. | Try again after a pause, a write only with an Idempotency-Key. If it keeps failing, send support the requestId. |
500RESPONSE_ |
An answer failed its own declared shape: a fault on Brevily’s side. | Try again after a pause, a write only with an Idempotency-Key. If it keeps failing, send support the requestId. |
500UNHANDLED |
Something failed on Brevily’s side; the request itself may be fine. | Try again after a pause, a write only with an Idempotency-Key. If it keeps failing, send support the requestId. |
503AUTH_ |
The key could not be checked just now: a fault on Brevily’s side, not a refused key. | Try again after a pause, a write only with an Idempotency-Key. If it keeps failing, send support the requestId. |
503MAINTENANCE |
A write while the organisation is in a maintenance window; reads still answer. details.until says when it ends. |
Send it again after Retry-After seconds. |
503SCHEMA_ |
Brevily is being updated; nothing saved is affected. | Send it again after Retry-After seconds. |
Codes no call here answersPermalink
Listed so that every code has its meaning.
| Code | What it means | What to do |
|---|---|---|
400COMPOSE_ |
A ?parts= naming parts a page does not have. |
No call here takes ?parts=. |
403CSRF_ |
A form token of the console’s own pages, missing or wrong. | /api takes no browser session, so no form token. |
405METHOD_ |
A method a path does not take. | Such a call answers 404 NOT_FOUND instead. |
500AUTH_ |
A server set up wrongly, found as it starts. | Such a server takes no calls. |
500CACHE_ |
A server set up wrongly, found as it starts. | Such a server takes no calls. |
500COMPOSE_ |
A server set up wrongly, found as it starts. | Such a server takes no calls. |
500TEMPLATE_ |
A page of the console failed to draw. | /api answers JSON, never a page. |
501UPLOADS_ |
A file sent to a server with nowhere to keep it. | The calls here take JSON, not files. |
504TIMEOUT |
Past a deadline the server sets for a request. | The calls here set none. A 504 with no code comes from the network on the way: send a read again, a write only with an Idempotency-Key. |
Handling themPermalink
- A 4xx is about the request: change it before sending it again. The exceptions are 409
IDEMPOTENCY_IN_FLIGHTand 429RATE_LIMITED, which ask you to wait. -
A 5xx is Brevily’s: wait and try again, a write only with an
Idempotency-Key(Retrying safely).MAINTENANCEandSCHEMA_BEHINDsay how long inRetry-After. - Show
messageto a person if it helps; never parse it.
Common mistakesPermalink
- Branching on
message: it can change. Branch oncode. - Retrying a 400 unchanged: it answers the same, and counts against the rate limit each time.
- Reading a 404 as “deleted”: it also answers a wrong organisation code, or a call that does not exist.
- Dropping
requestId: log it with every refusal, or support cannot find the request.
Type a call, a field or a guide.