Errors

API errors are JSON data. Use the HTTP status and stable code to select a recovery path, then validate any data against that operation’s generated error schema. Procedure errors can also include status, defined, and inferable. Do not depend on a JavaScript exception class, object identity or the wording of message. A client in Python, Go or another language uses the same documented fields. The generated API reference is authoritative for the deployed response shapes; an internal SDK or service refactor does not create a second public error envelope. This validation example illustrates one documented response. Read the operation schema for the available issue fields and limits:

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Input validation failed",
  "data": {
    "issues": [
      {
        "path": ["limit"],
        "message": "Too big: expected number to be <=100"
      }
    ],
    "truncated": false
  }
}

Common status codes

Status	Meaning	Client action
`400`	The request could not be decoded or did not match the input schema.	Correct the request. Do not retry unchanged.
`401`	The bearer credential is missing, invalid, expired, or unusable for this environment.	Obtain a valid credential.
`403`	The verified actor lacks one or more required permissions.	Request the missing authority or choose another operation.
`404`	The resource does not exist in the verified organization or is not visible.	Confirm the identifier and tenant context.
`409`	Current state conflicts with the requested mutation.	Read current state and reconcile revisions or idempotency keys.
`413`	The transport body exceeds its byte limit.	Reduce the request body.
`415`	The request media type is unsupported.	Use the media type declared by OpenAPI.
`422`	The request is syntactically valid but violates a domain rule.	Correct the referenced resource or domain value.
`429`	A rate limit was reached.	Wait for `data.retryAfterSeconds` when present.
`500`	The service could not complete the request because of an unexpected failure.	Preserve the request reference and check state before replaying a mutation.
`503`	A required downstream capability is temporarily unavailable.	Retry only when the operation is safe; use backoff.

Request references

Responses produced by the API include X-Request-Id. Save that value with the operation ID, HTTP status and approximate UTC time when investigating a failure. An upstream gateway or network interruption may return a response without the API’s error body or request reference; do not assume that an arbitrary HTML or empty response matches the schema. Request references help correlate an operation across service reports. They are not credentials, and they do not guarantee that every internal hop has a recorded distributed trace. When contacting support, share the reference and a description of the operation; omit access tokens, client secrets, patient data, signed URLs and raw provider responses.

Unknown and transient failures

Treat a malformed error body or an unrecognized code as an unknown failure. Preserve the reference and fall back to a safe user message; do not interpret exception text or allow an unknown error to imply success. A temporary failure does not prove that a mutation had no effect. Follow retries and idempotency before trying again. Reuse an operation’s documented idempotency key with the same semantic input, or read current state when the operation has no replay guarantee.

Get started

Core concepts

API guides

Common status codes

Request references

Unknown and transient failures

​Common status codes

​Request references

​Unknown and transient failures

Common status codes

Request references

Unknown and transient failures