Errors

The API follows standard GraphQL error reporting. A response can carry data, errors, or both — so always check for an errors array, not just the HTTP status.

Error shape

Errors come back in a top-level errors array. Each entry has a human-readable message:

{
  "errors": [
    { "message": "You don't have permission to read companies." }
  ],
  "data": null
}

When a query asks for several things and only part fails, you may get partial data alongside errors — the failed fields are null and the rest resolve normally.

Two kinds of message

• Validation and permission errors carry a specific, actionable message — for example a missing required field, an invalid argument, or a permission your token's roles don't grant. Surface these; they tell you what to fix.
• Unexpected server errors are deliberately redacted to a generic "Internal server error" so internal details never leak. These aren't something your request can fix — retry, and if it persists, contact support.

Handling errors

Common cases to handle:

• Authentication — a missing, malformed, or revoked token is rejected. Make sure the Authorization: Bearer … header is present and the token is valid.
• Permissions — "You don't have permission…" means your token's roles are too narrow. Grant the needed role under Settings → Developer → API tokens or use a token that has it.
• Validation — fix the input the message points to and retry.
• Transient server errors — retry with backoff; escalate if it persists.