Errors and Resilience
A professional integration does not treat errors as one undifferentiated failure. Identity, operation permission, resource scope, validation, and transient service conditions each produce a different HTTP status code.
How to interpret the error types
- 401 Unauthorized: authentication failure. The access token is missing or expired. Your backend should obtain a new token with its client credentials.
- 403 Forbidden: permission denied. The required scope or account access is missing.
- 404 Not Found: the resource does not exist, or it falls outside your tenant boundary.
- 400 Bad Request: validation failure. Reports missing, unknown, or business-rule-violating fields.
- 409 Conflict: the same
Idempotency-Keywas reused with a different request body, or the resource cannot accept the operation in its current state. - 429 Too Many Requests: rate limit exceeded. Wait the number of seconds given in the
Retry-Afterresponse header. - 500/502/503/504: the server or gateway could not complete the request temporarily. Retry only safe/idempotent operations, using exponential backoff with jitter.
Why idempotency matters
The response to a POST can be lost on the network even though the record was created
on the server, leaving the client unsure. When you send a unique Idempotency-Key of
8–128 characters on record-creating endpoints, a retry with the same key and the same
body will not create a second record. A replayed response carries the
Idempotency-Replayed: true header.
Rate limit headers
Every response reports the current rate limit through three headers:
X-RateLimit-Limit: requests allowed per window.X-RateLimit-Remaining: requests left in the window.X-RateLimit-Reset: seconds until the quota refreshes.
Pagination
List endpoints return a data array plus meta and links objects. Read the next page
from links.next rather than incrementing the page number yourself, and treat
meta.total_pages as the stopping condition. The maximum page size is 100.