Handling errors

The API uses HTTP status codes: 2xx for success, 4xx for a problem with the request, 5xx for a problem on the platform’s side. Every error has the same JSON body.

The error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such event: 'EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30'.",
    "param": "id",
    "doc_url": "https://developer.masterconf.com/errors/codes#resource_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

• type: the family of the error. Five values, listed below.
• code: the precise reason, such as resource_missing. Stable: branch on it.
• message: an English explanation for a developer. It may change: never branch on it, and never show it as it is to your own users.
• param: the parameter at fault, such as limit or starting_after, or null.
• doc_url: the page of the code in this documentation.
• request_id: the identifier of the request, to quote to support. See Request IDs.

The error codes page lists every code with what it means and what to do.

Type and code

type tells you how to react; code tells you exactly what happened.

• invalid_request_error (400, 404): the request is wrong. Fix it before sending it again; the same request fails the same way.
• authentication_error (401): the key could not be used. Check the Authorization header and the key.
• permission_error (402, 403, 423): the key is valid but the call is not allowed: a scope, the plan, or a suspended organization. Retrying changes nothing until that changes.
• rate_limit_error (429): too many requests. Wait, then retry. See Rate limits.
• api_error (500, 503): the platform failed. Retry later.

New codes can be added within v1. If you meet a code you do not know, act on the HTTP status and the type.

Retrying

Retry only what can succeed later:

• 500 api_error and 503 service_unavailable: retry with an exponential backoff. A 503 carries a Retry-After header: wait at least that many seconds.
• 429 rate_limit_exceeded: wait for the delay of X-RateLimit-Reset, then retry.

Never retry another 4xx unchanged. Every operation is a GET that changes nothing, so a retry is always safe.

Unknown routes

A GET to a path under /v1/ that matches no operation answers 404 route_missing, with the usual error object.

A request that is not a GET or a HEAD, or whose path is outside /v1/, is not answered by this API: its answer does not carry this error object.