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 or 403, 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 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

Each API key is limited to 100 requests in a row. The count starts over only after 60 seconds pass with no accepted request on the key, so a key that never pauses for a full minute is refused after its 100th request, even at fewer than 100 requests a minute.

A refused request receives the same response as an invalid key: 401 with error.code UNAUTHORIZED and the message Invalid or expired API key. The response has no Retry-After header.

If a key that was working starts returning that response, stop sending requests on that key for 60 seconds, then retry once before treating the key as revoked. Refused requests do not extend the wait.

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