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.
Example response (401 Unauthorized):
{
"error": {
"code": "unauthorized",
"message": "authentication required"
}
}Use the code and status for application logic. Keep the message for diagnostics rather than matching its wording.
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 scope 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. |
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.