Errors

Errors

A refusal answers its status and a body with a plain code.

Example answer

A refusalhttp
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.

The error body
NameTypeDescriptionAllowed values
codestringStable, for code to read: the list below.—
messagestringFor people; it can change.—
detailsobjectEvery 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).—
requestIdstringThe 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.

The codes a call can answer
Code What it means What to do
400IDEMPOTENCY_KEY_INVALID The Idempotency-Key is longer than 255 characters. Send a shorter key: a UUID does.
400QUERY_INVALID The query string is past the parser’s limits: too many parameters, or a value too long. Send fewer parameters or shorter values.
400VALIDATION_FAILED 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_DENIED 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_FOUND 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_IN_FLIGHT 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_TOO_LARGE The body is over 1 MB; details.maxBytes says the limit. Send less in one call.
415UNSUPPORTED_MEDIA A body sent as something other than JSON to a call that reads one. Send content-type: application/json.
422IDEMPOTENCY_MISMATCH This key was first sent with a different request: another method, path, query or body. Use a new key for a new request.
429RATE_LIMITED 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_INVALID 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_UNAVAILABLE 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_BEHIND 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.

The codes no call here answers
Code What it means What to do
400COMPOSE_PARTS A ?parts= naming parts a page does not have. No call here takes ?parts=.
403CSRF_INVALID A form token of the console’s own pages, missing or wrong. /api takes no browser session, so no form token.
405METHOD_NOT_ALLOWED A method a path does not take. Such a call answers 404 NOT_FOUND instead.
500AUTH_UNBOUND A server set up wrongly, found as it starts. Such a server takes no calls.
500CACHE_UNBOUND A server set up wrongly, found as it starts. Such a server takes no calls.
500COMPOSE_UNKNOWN_ACTION A server set up wrongly, found as it starts. Such a server takes no calls.
500TEMPLATE_RENDER A page of the console failed to draw. /api answers JSON, never a page.
501UPLOADS_UNAVAILABLE 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_FLIGHT and 429 RATE_LIMITED, which ask you to wait.
  • A 5xx is Brevily’s: wait and try again, a write only with an Idempotency-Key (Retrying safely). MAINTENANCE and SCHEMA_BEHIND say how long in Retry-After.
  • Show message to a person if it helps; never parse it.

Common mistakesPermalink

  • Branching on message: it can change. Branch on code.
  • 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.