Error envelope
message field is intended for log lines and developer diagnostics. Don’t surface it verbatim to end users — phrasing may change between releases.
Status code matrix
| Status | When to expect it | What to do |
|---|---|---|
200 | Successful request. | Process the response body. |
400 | Malformed input (bad JSON, invalid query parameter, validation failed). | Inspect message and fix the request. |
401 | Missing or invalid Bearer token. | Re-check the Authorization header. See Authentication. |
403 | Token is valid but lacks the required ability for the endpoint. | Email support to widen the token’s scope. |
404 | The resource (company, list, set) does not exist. | Confirm the identifier; some IDs expire after 24 hours — see Batching. |
422 | Request well-formed but semantically invalid (for example, mutually exclusive filter fields). | Inspect message, adjust the body. |
429 | Too many requests. | Back off and retry. See Rate limits. |
500 | Unexpected server error. | Retry with exponential backoff; if persistent, contact support@thedatacity.com. |
503 | Service unavailable, usually during a deploy. | Retry after a short delay. |
Retrying
Retry429, 500, 502, 503, and 504 with exponential backoff. Do not auto-retry 400, 401, 403, 404, or 422 — the request will fail again the same way.