Errors
The API returns 20 error codes. Branch on the code, not on the message.
An error has an HTTP status and a body with a stable code and a message. The message is a sentence in English for the person building the automation. It can change. The code doesn’t.
{
"code": "not_found",
"message": "ContactZapp has nothing at this address for this API key. Check the id or the trigger name."
}All codes
This list is built from the API’s own spec, so it has every code the API can return.
| Code | Status | Send again? | What it means |
|---|---|---|---|
api_key_missing | 401 | No, fix the request | The request has no API key. |
api_key_invalid | 401 | No, fix the request | The API key is not valid. It may have been revoked. |
insufficient_scope | 403 | No, fix the request | The API key does not have the scope this operation needs. |
rate_limited | 429 | Yes | Too many requests. Wait the number of seconds in the Retry-After header. |
internal_error | 500 | Yes | Something went wrong in ContactZapp. Try again. |
unavailable | 503 | Yes | ContactZapp could not check the request just now. Try again. |
invalid_parameter | 400 | No, fix the request | A parameter is not usable, for example a limit out of range, a cursor from another request, or more than one filter. |
not_found | 404 | No, fix the request | There is nothing at this address for this API key. |
invalid_body | 400 | No, fix the request | The request body is not a contact. |
invalid_date | 400 | No, fix the request | A date in the request is not a real date. |
empty_contact | 400 | No, fix the request | The contact has no values. |
no_account_to_write_to | 422 | No, fix the request | The user has no two-way account that keeps an address book and is not paused. |
contact_gone | 409 | No, fix the request | The contact was merged into another contact or deleted. |
contact_pending_review | 409 | No, fix the request | The contact waits in Review duplicates. |
contact_changed | 409 | Yes | The contact changed while it was being written. Try again. |
idempotency_key_invalid | 400 | No, fix the request | The Idempotency-Key header is empty, too long or has more than one value. |
idempotency_key_reused | 422 | No, fix the request | This Idempotency-Key was already used with a different request. |
idempotency_key_in_progress | 409 | Yes | A request with this Idempotency-Key is still being handled, or did not finish. |
body_too_large | 413 | No, fix the request | The request body is too large. |
unknown_field | 400 | No, fix the request | The body carries a field a contact write does not take: a misspelt name, a read-only field such as id or updatedAt, or a field the contact does not show. Nothing was written. |
What to do
- 429, 500 and 503. Wait, then send the same request again. For a 429, wait the seconds in
Retry-After. See Rate limits. - 409
contact_changed. The contact changed while we wrote it. Read it again and resend. - Other 4xx. The request is wrong. Sending it again gives the same answer, so change it first.