Error Handling

OwlFlow returns errors in the standard GraphQL format, enriched with machine-readable codes and request correlation IDs.

Error Format

Errors are returned in the errors array of the response:

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "requestId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

Error Codes

Code	Description
UNAUTHENTICATED	Missing or invalid Bearer token.
FORBIDDEN	The authenticated user does not have permission for the action.
BAD_USER_INPUT	Validation failure or invalid arguments provided.
UPSTREAM_ERROR	An error occurred when communicating with an internal backend service.
INTERNAL	An unexpected server-side error.

Request Correlation

Every error includes a requestId. Please provide this ID when reporting issues to help us trace the request in our logs.