Error handling

All examples assume an authenticated request — see Authentication for getting and using a token.

GraphQL errors

GraphQL errors appear in the errors array alongside a null data field. Each error includes a message and an extensions.code:

{
  "errors": [
    {
      "message": "Credential not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ],
  "data": null
}

Always check for errors before reading data. A response can contain both — for example, a partial success where some fields resolved and others did not.

Common error codes

Code	Meaning	Action
UNAUTHENTICATED	Token missing, expired, or invalid	Request a new token and retry
FORBIDDEN	Token valid but insufficient permissions	Verify the associated user's roles
NOT_FOUND	The requested resource does not exist	Check the ID in your request
BAD_USER_INPUT	Invalid argument or input value	Check arguments against the operation reference

Token endpoint errors

Errors from POST /oauth/token use the OAuth 2.0 error format — a JSON object with error and error_description fields, not a GraphQL errors array:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Code	Cause	Resolution
invalid_client	Wrong client_id, wrong client_secret, or expired client	Check error_description for details; if the client has expired, ask an administrator to rotate the secret
invalid_request	Missing required parameters	Include grant_type, client_id, and client_secret
unsupported_grant_type	Only client_credentials is supported	Use "grant_type": "client_credentials"

HTTP status codes

Status	Meaning	Action
400 Bad Request	Malformed request or invalid input	Check request body and headers
401 Unauthorized	Authentication failed	Request a new token
403 Forbidden	Authenticated but insufficient permissions	Verify user roles
404 Not Found	Endpoint or resource not found	Check the URL and resource ID
429 Too Many Requests	Rate limit exceeded	See Rate limiting
500 Internal Server Error	Unexpected server error	Retry with exponential backoff; contact support if the issue persists