Error handling

Check the HTTP status before reading a response as a successful result. API errors return an error object containing a stable code and a human-readable message.

Use the code and status for application logic. Keep the message for diagnostics rather than matching its wording.

Status codes

For 400, check the input and the operation's state requirements. For 401, check your key and permissions. For 404, check the node ID and whether it was deleted. For 429, wait for the Retry-After interval.

If credit or billing prevents the operation (402), resolve the account's credit or billing state. Server and upstream failures (500, 502, 503) require checking the outcome before retrying a mutation.

Malformed JSON or unsupported request content types may be rejected before the endpoint runs. Handle unexpected or non-JSON error bodies as well.

Retry carefully

Retry reads after transient failures using bounded exponential backoff. For 429 responses, follow the rate limiting guidance.

A timeout or connection error does not establish that a mutation failed. Check node state before repeating a lifecycle operation. After an interrupted create request, list nodes before creating another one. Node creation does not accept an idempotency key.

A 202 Accepted creation response means provisioning is still in progress. A successful update request also starts background work; inspect the node to determine the final outcome.

Example error response

{
  "error": {
    "code": "unauthorized",
    "message": "authentication required"
  }
}

HTTP status codes

Status	Meaning	What to do
`400`	Invalid input or node state	Check request fields and the operation's state requirements.
`401`	Authentication or permission mismatch	Check the API key and permissions.
`402`	Account credit or billing prevents the operation	Resolve the account's credit or billing state.
`404`	Node not found	Check the identifiers and whether the node was deleted.
`429`	Rate limit exceeded	Wait for `Retry-After` before retrying.
`500`	Unexpected server error	Record the failure and reconcile the operation's outcome.
`502`	Upstream request failed	Retry reads with backoff; reconcile mutations first.
`503`	A dependency or required service is unavailable	Retry with backoff when the service recovers.