Errors

Every error response is JSON with an error message. Some errors add a code.

Status codes#

Status	Body	When
`400`	`{"error":"<message>"}`	Invalid JSON or an invalid query parameter. The message names the field.
`400`, `404`, `409`, `500`, `502`	`{"error":"<message>","code":"<code>"}`	Errors from the prospect write layer. See the codes below.
`401`	`{"error":"<message>"}`	Missing or invalid token. See Authentication.
`404`	`{"error":"<Resource> not found."}`	The resource does not exist in this workspace, the id belongs to another workspace, or the id is not a UUID.
`409`	`{"error":"<message>"}`	The resource is in a state that does not allow the action.
`422`	`{"error":"<message>"}`	An idempotency key was reused with a different request.
`429`	`{"error":"Rate limit exceeded (60 requests/minute)."}`	See Rate limits.
`500`	`{"error":"Couldn't read this resource: <message>"}`	A database failure on a read. The fault is on the anymail side.

Unknown query parameters and unknown body fields are ignored. A known parameter with an invalid value returns 400.

The prospect endpoints and the campaign enrolment call return a code next to the message.

Code	Status	Meaning
`invalid-email`	`400`	The address failed validation. The message is `Enter a valid email address.`
`duplicate`	`409`	The address already exists in the workspace. Use `PATCH /prospects/{id}` to change it.
`not-found`	`404`	The prospect does not exist in this workspace.
`company-failed`	`502`	Grouping the prospect into a company failed.
`db-error`	`500`	A database failure on the anymail side.

POST /suppressions returns 409 with code: "duplicate" and also kind and value when the target is already excluded.

Endpoints that take a JSON body return these 400 messages.

Message	Cause
`Request body too large.`	The body exceeds the limit of the endpoint. See Limits and good practice.
`Expected a JSON body.`	The body is empty.
`Body is not valid JSON.`	The body does not parse.
`Body must be a JSON object.`	The body is an array or a scalar.

Send Content-Type: application/json with every body.

4xx means the request needs a change. Do not retry it unchanged. The exceptions are 409 with the message A request with this Idempotency-Key is still being processed. and 429.
5xx means a fault on the anymail side. Retry with backoff. Reuse the same idempotency key so the retry cannot create a duplicate.