Errors

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "status": 400
}

Error Codes

Status	Error Code	Description
`400`	`bad_request`	Missing or invalid request body
`401`	`unauthorized`	Missing, invalid, or expired API key
`403`	`forbidden`	API key lacks required scope
`404`	`not_found`	Resource not found or not accessible
`410`	`expired`	Credential has expired
`413`	`payload_too_large`	Request body exceeds 2MB limit
`429`	`rate_limited`	Too many requests (200/min per identity, 60/min per IP)
`429`	`quota_exceeded`	Daily send limit reached (50 emails/day)
`500`	`internal_error`	Server error

{
  "error": "bad_request",
  "message": "to, subject, and text are required",
  "status": 400
}

{
  "error": "not_found",
  "message": "Message not found",
  "status": 404
}

This also occurs when trying to access a message that belongs to a different identity.

{
  "error": "forbidden",
  "message": "Missing required scope: mail:send",
  "status": 403
}

{
  "error": "rate_limited",
  "message": "Too many requests",
  "status": 429
}

{
  "error": "quota_exceeded",
  "message": "Daily send limit reached (50/day). Resets at midnight UTC.",
  "status": 429
}

{
  "error": "expired",
  "message": "Credential \"my-api-key\" has expired (2026-01-01T00:00:00.000Z)",
  "status": 410
}