details is present only when useful.
{
"error": {
"code": "validation_error",
"message": "companyWebsite: Invalid url; alertEmails.0: Invalid email"
}
}
path: reason, so a client can fix everything in one round trip.
| HTTP | code | When |
|---|---|---|
| 400 | validation_error | Invalid or missing fields (message lists each), bad enum value, bad date, since ≥ until, bad view, non-numeric limit, malformed ID, invalid Idempotency-Key, exact and fuzzy filters sent together, empty PATCH |
| 400 | invalid_json | Request body is not valid JSON |
| 400 | invalid_cursor | Cursor was tampered with or malformed |
| 401 | unauthorized | Missing, malformed, unknown, revoked or expired API key |
| 403 | insufficient_scope | Key lacks the scope the endpoint needs |
| 404 | not_found | Unknown ID, or an ID from another organisation. Unknown paths also return 404 |
| 404 | entity_not_found / source_not_found | Fuzzy lookup matched nothing |
| 405 | HTTP method not supported on that path | |
| 409 | ambiguous_entity / ambiguous_source | Fuzzy lookup matched several companies; details.candidates lists them |
| 409 | idempotency_conflict | Idempotency-Key reused with a different body |
| 409 | idempotency_in_progress | The original request with that key is still running |
| 409 | refresh_in_progress | A tracker run is already in progress |
| 409 | entity_paused | Refresh requested for a paused entity |
| 429 | rate_limited | Per-key rate limit exceeded; see Retry-After and details |
| 500 | internal_error | Unexpected server error |
| 500 | auth_unavailable | The key could not be verified (transient) |
| 502 | enrichment_failed | Draft enrichment failed or returned an invalid result |
| 502 | refresh_failed | The tracker backend could not queue a refresh |
| 503 | idempotency_unavailable | Idempotency storage was unavailable; retry later |