The error format returned by the GraphQL API and REST endpoints, status codes, and how to handle them.

GraphQL errors

GraphQL requests that reach the server usually return HTTP 200, even when an operation fails. Check the errors array in the response body. Each error has this shape:

{
  "data": null,
  "errors": [
    {
      "message": "A valid email address is required",
      "statusCode": 400,
      "code": "BAD_REQUEST",
      "details": {
        "path": ["createSupportRequest"],
        "error": "Bad Request"
      }
    }
  ]
}

Field	Description
`message`	Human-readable description. Safe to show to users for validation errors.
`statusCode`	HTTP-style status code for the failure (for example `400`, `401`, `403`, `404`, `409`, `429`, `500`).
`code`	Machine-readable error code; see the table below.
`details.path`	The field path in the operation that failed.
`details.error`	Short reason phrase (for example `Bad Request`) or the code.

Codes

`code`	`statusCode`	Meaning
`BAD_REQUEST`	400	Invalid input, such as a missing field or a value that is too long.
`BAD_USER_INPUT`	422	Input is well-formed but cannot be processed.
`UNAUTHENTICATED`	401	Missing, invalid, or expired token. See Authentication.
`FORBIDDEN`	403	Signed in, but not allowed to perform this operation.
`INTERNAL_SERVER_ERROR`	404, 409, 500, ...	Other failures. Use `statusCode` to tell them apart: `404` not found, `409` conflict (for example an email that is already subscribed), `500` server error. Rate-limit errors also use this code; see Rate limits.
`GRAPHQL_PARSE_FAILED`, `GRAPHQL_VALIDATION_FAILED`	-	The query itself is invalid (syntax error, unknown field, wrong argument type). The HTTP response status is `400`. Fix the query.

Branch on statusCode

code is coarse for some failures. For reliable handling, branch on statusCode and use message for display.

Some mutations return an envelope type (for example SupportRequestApiResponse) with its own status, statusCode, and message fields. When the mutation succeeds, status is SUCCESS and data holds the result. Failures are reported through the errors array as above.

REST errors

REST endpoints return the HTTP status code of the failure, with this JSON body:

{
  "status": "ERROR",
  "cause": "Resume must be a PDF, DOC or DOCX file",
  "message": "Failed to process request",
  "statusCode": 400
}

Field	Description
`status`	Always `ERROR` for failures.
`cause`	The specific reason. For validation failures this can be an array of messages, one per invalid field.
`message`	Generic summary.
`statusCode`	Same as the HTTP status code.

Handling errors

Status	Retry?	What to do
400, 422	No	Fix the input. Show `message` (or `cause`) to the user.
401	Once	Refresh the token, then retry.
403	No	The account lacks permission.
404	No	The resource does not exist or is no longer available.
409	No	Conflict with existing data (for example a duplicate). Treat as already done where that makes sense.
413	No	The upload is too large.
429	Yes, later	Wait for the `Retry-After` period. See Rate limits.
5xx	Yes	Retry with exponential backoff (for example 1 s, 2 s, 4 s), up to a few attempts.

Errors

GraphQL errors

Codes

Response envelopes

REST errors

Handling errors

On this page