Error Handling

API errors use an HTTP status plus a machine-readable error envelope. A typical response is:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": {
      "field": "name",
      "requestId": "req-example"
    }
  },
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Some route-specific errors are simpler, so always inspect both the HTTP status and the response schema for the operation.

Common Status Codes

Status	Meaning	Response
400	Invalid query, body, or relationship	Correct the fields in error.details when present.
401	Missing or invalid authentication	Check the header, environment, expiration, and revocation state.
403	Authenticated but not allowed	Review key scopes, user permissions, organization context, and restrictions.
404	Path or record not found	Verify the route and ID; inaccessible records can also fail closed.
409	Conflict or duplicate value	Re-read current state before retrying.
429	Rate limit exceeded	Wait for Retry-After, then retry with backoff.
500+	Server or dependency failure	Retry safe reads, then contact support with the request ID.

Retry Safely

Retry GET requests with exponential backoff and jitter. Retry writes only when you know the operation is idempotent or you can verify whether the first attempt committed. Never loop indefinitely on validation or permission errors.

Log the HTTP method, path template, status, error code, and request ID. Redact API keys, authorization headers, cookies, and confidential record data.