Errors and status codes
What each response means, and whether retrying will help.
Errors always come back in the same shape, so one handler covers all of them:
The shape
{
"error": {
"code": "validation_failed",
"message": "email must be a valid address",
"details": { "field": "email" }
}
}message is written to be shown to a person. code is stable and safe to branch on; details is present when there’s something specific to point at.
The codes
| Status | Means | Do |
|---|---|---|
| 200 / 201 | Updated / created | Nothing |
| 204 | Deleted | Nothing — there’s no body |
| 401 | Key missing, wrong or revoked | Fix the key. Never retry |
| 404 | Not found, or not in your account | Check the id. Never retry |
| 409 | Conflicts with something that exists | Usually update instead of create |
| 422 | Body failed validation | Read details. Never retry unchanged |
| 429 | Rate limited | Wait Retry-After, then retry |
| 5xx | Our fault | Retry with backoff |
The rule of thumb: 4xx means change something before you try again; 429 and 5xx are the only ones worth retrying unchanged.
Why you get 404 rather than 403
An id belonging to another account returns 404, not 403. That’s deliberate: distinguishing “this doesn’t exist” from “this exists but isn’t yours” would let anyone probe for valid ids.
So a 404 on something you’re sure exists usually means you’re using a key from a different account.
Common issues
422 on an address that looks fine
Check for whitespace or a trailing comma from a CSV. The details object names the field.
409 creating a contact
You shouldn’t see it on POST /contacts — that upserts. If you do, it’s a list name colliding.
Intermittent 5xx
Retry with backoff. If it persists, note the time and get in touch — a persistent 5xx is a bug on our side, not something to work around.
FAQs
Are error codes stable?+
Yes — branch on code rather than matching on message, which is prose and may be reworded.
Is there a request id for support?+
Not yet. Send the endpoint, the time and the body you posted — minus anything sensitive — and that’s enough to find it.