Errors
Handle API failures and decide when to retry.
HTTP status codes
Check the HTTP status before parsing the response. Successful calls use2xx; endpoint references describe their success bodies. HTTP 204 has no response body.
| Status | Meaning | What to check |
|---|---|---|
400 | Invalid input | Required fields, field types, filters, and pagination bounds. |
401 | Authentication failed | Missing, invalid, or revoked bearer token. |
403 | Access denied | Public API access and permissions for the resource. |
404 | Resource or endpoint not found | UID, path, method, and resource visibility. Requests outside the key owner’s visibility also return 404. |
409 | Conflict | Read the current resource and the error details before retrying. |
422 | Validation failure | The error details and the endpoint’s constraints. |
429 | Rate limit exceeded | Wait until the reset time in X-SiitApi-Reset. |
5xx | Server error | Retry read requests with a delay; check the outcome before repeating a write. |
JSON errors
Most API errors return anerror string and a human-readable troubleshoot string. For example, an authentication failure returns HTTP 401:
{
"error": "Authentication required",
"troubleshoot": "Missing or invalid access token"
}
troubleshoot as optional. For example, exceeding the pagination boundary returns HTTP 400 with only error. Use HTTP status codes for programmatic handling rather than matching human-readable messages.
Rate-limit errors
HTTP429 returns plain text rather than the JSON error object:
Throttled
X-SiitApi-Reset as a Unix timestamp in seconds and wait until that time before retrying. See rate limiting for the quota and headers.
Retrying requests
Use increasing delays for transient failures on reads. After a timeout or server error on a write, check whether it succeeded before repeating it: retrying a create operation can create duplicates. The batch import endpoint supports idempotency throughimport_source and external_id. Do not assume the same behavior for other endpoints.
JSON error attributes
{
"error": "<string>",
"troubleshoot": "<string>"
}