{ } JSONBucket
62 endpoints v1.1.2 OpenAPI

Error codes.

Every failure returns the same shape, whatever went wrong. Branch on code, which is stable; message is written for people and may be reworded.

Shape

One object, always under an error key.

param appears only when a single parameter caused the failure, and names it exactly as the endpoint documents it. Success responses never contain error, so its presence is a reliable test.

400 Bad Request
{
  "error": {
    "code": "invalid_parameter",
    "message": "unknown timezone \"Nowhere\", expected an IANA name like Europe/Stockholm",
    "param": "tz"
  }
}

Codes

CodeStatusMeaningWhat to do
invalid_parameter 400 A parameter was present but unusable — out of range, the wrong type, or not one of the accepted values. Read param and message; the message states the accepted range or values.
missing_parameter 400 A required parameter was absent. Supply the parameter named in param.
bad_request 400 The request was malformed as a whole rather than in one field — unparseable JSON, or a body past the size limit. Check the body parses, and that its media type matches what the endpoint documents.
not_found 404 No such route, or no resource with that identifier. Compare the path against the schema. A removed endpoint looks the same as one that never existed.
rate_limited 429 Too many requests from your address. Wait for Retry-After seconds. Back off rather than retrying immediately; a rejected request does not consume future capacity.
internal_error 500 A fault on our side. No detail is exposed, deliberately. Retry once. If it persists, quote the X-Request-Id from the response headers.

Worth knowing

Three things that surprise people.

Validation endpoints answer 200 on invalid input. Asking whether an IBAN is valid and learning that it is not is a successful question, so /v1/validate/* returns 200 with "valid": false and a reason. A 4xx there means the request itself was wrong.
/v1/status/{code} returns the code you ask for. A 503 from it is correct behaviour, not a fault. It exists so you can exercise your client's error paths.
A 429 may come from the edge rather than the API. Rate limiting is applied in front of the service, so a throttled request can be rejected before it reaches an endpoint. Always read Retry-After.