Standard response envelope
A successful response always hassuccess: true, an HTTP 2xx status, and a data object containing the result. The links array carries pagination or related-resource links when applicable.
The payload for this response. An object for single-resource endpoints; an array for list endpoints.
Error envelope
When a request fails,success is false and the envelope adds a machine-readable name field you can use to drive error-handling logic without parsing the message string.
A machine-readable error identifier. Use this field — not the
message — to branch your error-handling logic.A human-readable description of what went wrong. Useful for logging; do not parse this string programmatically.
HTTP status codes
Machine-readable error names
Use thename field in your application code to handle specific error conditions without relying on message strings, which may change.
Handling errors in code
Retry guidance
Not all errors warrant a retry. Use this table to decide when to retry automatically and when to surface the error to the operator.Exponential back-off for 429 and 5xx
When you encounter a429 or 5xx response, wait before retrying. A simple exponential back-off strategy:
Python
For
429 Too Many Requests, check whether the response includes a Retry-After header specifying exactly how many seconds to wait before sending the next request.Pagination on list endpoints
List endpoints (e.g.GET /v2/api/entities) use offset pagination. The links array in the response envelope contains next and prev cursor URLs when additional pages are available. High-volume streams such as signals also support cursor-based pagination, which is preferred for production polling workloads.