Errors

A failed request returns an HTTP status of 400 or above and a JSON body. The body has one of two shapes, depending on where the request was refused:

• API key errors come from the key check that runs before any operation. They return 401, 403 or 429, with the fields nested under error.
• Operation errors come from the operation itself: validation, missing resources, state conflicts, server errors, and unknown paths. They return the fields at the top level.

How to read an error

1. Branch on the HTTP status first. It is reliable whichever shape the body has.
2. Read code at the top level of the body.
3. If there is no top-level code, read error.code. Only the API key check returns this shape.
4. If code is BAD_REQUEST and issues is present, read issues to find which fields were rejected.

const body = await response.json();
const code = body.code ?? body.error?.code;
const message = body.message ?? body.error?.message;

The status alone does not always tell you the shape. A 401 or a 429 always comes from the key check and is nested, but a 403 can be nested (from the key check) or flat (from an operation). The fallback above handles both.

API key errors

The key check runs before the request reaches any operation. It returns a body with error.code and error.message, and no other fields:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Include Authorization: Bearer <key> header."
  }
}

Rate limits

A rate limited key returns 429 with error.code RATE_LIMITED and a Retry-After header that gives the number of seconds to wait. Wait that long, then retry. The key is still valid, so do not rotate or revoke it.

The limit itself is described in Authentication.

Operation errors

Every error raised after the key check returns the fields at the top level:

{
  "message": "Input validation failed",
  "code": "BAD_REQUEST",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["name"],
      "message": "Required"
    }
  ],
  "data": {
    "code": "BAD_REQUEST",
    "httpStatus": 400,
    "path": "createProject"
  }
}

Validation issues

When the request does not match the operation's schema (a missing field, a wrong type, a value outside the allowed range or enum), the response is 400 with code BAD_REQUEST, message Input validation failed, and an issues array. Each issue has:

Some issue codes carry extra fields that describe the problem, such as expected and received on invalid_type, or minimum on too_small. A number field that is missing or not numeric reports Expected number, received nan, not Required.

Some rules are checked after the schema, such as an unknown filter slug. Those are also 400 BAD_REQUEST, but they have no issues: the message names the problem and, where it can, the valid values.

Error codes