Errors
The API returns standard HTTP status codes with a JSON body. Every error body has a detail field. Other fields depend on where the error came from.
Common codes
Section titled “Common codes”| Code | Meaning |
|---|---|
400 |
The request was malformed or failed a rule. |
401 |
Missing, expired, or invalid token or API key. Authenticate again. |
403 |
Valid credentials, but your role does not permit this action. |
404 |
The record does not exist or is not visible to your company. |
409 |
The action conflicts with the record’s state, for example a pipeline move that needs a recorded decision first. |
413 |
An uploaded file is too large. |
422 |
The request body or query failed validation. |
429 |
Rate limited. See Rate Limits. |
500 |
Server error. Retry with backoff, and report it if it persists. |
503 |
The feature is switched off or temporarily unavailable. The detail says which. |
Body shapes
Section titled “Body shapes”- Most errors:
{"detail": "Not authenticated"}. - Validation (
422):detailis a list. Each entry names the field inloc, a message inmsgand the rule intype. - Coded errors:
{"detail": "...", "code": "GC-10000", "resolution": "..."}. Thecodeis stable andresolutionsays what to do. Codes are grouped by area, for exampleGC-11xxxfor sign-in and sessions andGC-15xxxfor contracts. - Unhandled errors:
{"detail": "...", "error": "...", "status_code": 500, "request_id": "..."}. A server error (5xx) also carries a shortreference. Quote it, or therequest_id, when you contact support. - Rate limited (
429):{"detail": "Rate limit exceeded", "limit": "..."}with aRetry-Afterheader.
Reading a 404
Section titled “Reading a 404”A 404 can mean the record does not exist or that it belongs to another company. The platform deliberately does not say which, to avoid confirming the existence of other customers’ data.