Error handling - Xem

When a request fails, the Xem API returns an HTTP status code and a JSON body:

{
  "error": "A valid recipient is required",
  "code": 400,
  "time": "2026-10-30T09:15:00Z"
}

Field	Meaning
`error`	What went wrong. Usually a sentence; for validation failures it describes each invalid field.
`code`	The HTTP status code, repeated for convenience
`time`	When the error happened, in RFC 3339 format

Rate-limit responses use their own body, described in Rate limiting.

Status codes

Status	Meaning	What to do
`400 Bad Request`	The request body or a parameter is invalid	Read `error`, fix the request, and do not retry unchanged
`401 Unauthorized`	The API key or access token is missing, invalid or expired	Check the `X-API-Key` header, or refresh your access token
`403 Forbidden`	Your key or account lacks permission for this action	Check the role or key permissions in your workspace
`404 Not Found`	The resource does not exist in your workspace	Check the id; resources from other workspaces are never visible
`409 Conflict`	The request conflicts with existing data, such as a reused `requestId`	Use a new id, or fetch the existing resource
`413 Payload Too Large`	The body is over the endpoint’s size limit	Send less data, for example smaller attachments
`429 Too Many Requests`	You exceeded the rate limit	Wait for `retry_after` seconds
`500 Internal Server Error`	Something failed on the server	Retry with backoff; contact support if it persists

Retry safely

Retry only errors that may succeed later: 429, 500 and network failures. Use exponential backoff with jitter, as shown in Rate limiting. When retrying a send, include the same requestId so the email is not sent twice. Do not retry 400, 401, 403, 404 or 409 without changing the request.

Get help

If an error persists, open an issue on GitHub or email team@xem.email. Include the endpoint, the status code, the time value and the error message, but never your API key.