errors

Comprehensive error reference guide including HTTP status codes and domain-specific exceptions

Error Reference Documentation

Errors

We use conventional HTTP status codes to indicate success or failure. In general:

  • 2xx: Success
  • 4xx: Request errors (fix the request)
  • 5xx: Server errors (retry with backoff; include requestId when contacting support)

Error responses share a consistent structure across all endpoints.

Error object (attributes)

status string

HTTP status code as a string, as JSON:API specifies (e.g., "400", "422", "500"). Use the response's HTTP status code if you need a number.


title string

Short, human-readable summary (e.g., "Validation failed").


code string

Rarely set. Don't rely on it being present; use the HTTP status code, title and detail instead.


detail string

Human-readable explanation that may include parameter-level context.


source nullable object

Where the error originated (optional).

  • parameter nullable string - Name of the request parameter with an issue.
  • pointer nullable string - JSON Pointer path (e.g., /data/attributes/email) when applicable.

HTTP status code summary

A general overview of HTTP status codes used throughout the API.

Code Status Description
400 Bad Request The usual status for a validation failure, such as a missing or invalid field value. Read detail (and source, when set) to see which field to fix, then resend the corrected request.
401 Unauthorized No valid authentication credentials provided. Provide valid credentials (Bearer token/API key); refresh/rotate if expired or revoked.
403 Forbidden The authenticated user lacks required permissions. Use an account/role with required permissions or request appropriate scopes.
404 Not Found The requested resource doesn't exist. Verify the resource ID and path; ensure the resource exists and is accessible.
409 Conflict The request clashes with the current state, for example a payroll locked for processing, or an Idempotency-Key reused with a different body or while the first request is still in progress. See the operation's description or the idempotency reference.
422 Unprocessable Entity The body doesn't match the resource's shape, for example an unknown attribute or relationship, or a value of the wrong JSON type. An Idempotency-Key over 255 characters also returns 422. Fix the body to match the documented schema.
500 Internal Server Error Something went wrong on our end. Retry with backoff; contact support if it persists.
SecuritybearerAuth
Responses
200

This is documentation only - not a real endpoint

get/errors
Request samples