Errors

Errors use HTTP status codes and a JSON body with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "message_expired",
    "message": "The retention period of this message ended. It is no longer available."
  }
}

Rely on code, not on message; messages may change. Validation errors add the invalid fields:

{
  "error": {
    "code": "invalid_payload",
    "message": "The limit field must not be greater than 100.",
    "fields": {
      "limit": ["The limit field must not be greater than 100."]
    }
  }
}

Error codes

Status	Code	Meaning	What to do
401	`unauthenticated`	The API key is missing, invalid or revoked.	Check the key.
403	`forbidden`	The key lacks the receiving permission, or the project is suspended.	Change the receiving access of the key.
404	`not_found`	The message, attachment, delivery or recipient does not exist or is outside the scope of the key.	Do not retry.
409	`message_not_stored`	The message is not (yet) in the message store.	Retry later.
409	`content_not_ready`	The parsed content is not available yet.	Retry later, or use the original message.
409	`content_failed`	The parsed content is not available and will not become available, for example for messages received before parsing was introduced.	Use the original message.
409	`delivery_not_retryable`	Only failed or cancelled deliveries can be retried.	Download a confirmed message again instead.
409	`retry_pending`	A retry of this delivery was already requested.	Wait for its result.
409	`endpoint_unavailable`	The webhook endpoint of the delivery was deleted or disabled.	Enable the endpoint first.
409	`idempotency_conflict`	The `Idempotency-Key` was already used for a different request.	Use a new key for a new request.
409	`request_in_progress`	A request with this `Idempotency-Key` is still being processed.	Retry after `Retry-After` seconds.
410	`message_expired`	The retention period of the message ended.	Do not retry. Metadata stays available.
422	`invalid_payload`	A parameter or header is invalid or missing.	Correct the request.
429	`too_many_requests`	A rate limit was exceeded.	Retry after `Retry-After` seconds.
503	`content_unavailable`	The parsed content cannot be read right now.	Retry later.

Unknown error codes may be added. Treat an unknown 4xx code as a permanent error of the request and an unknown 5xx as temporary.

Get started

Receiving email

Webhooks

Error codes

​Error codes

Error codes