Error Codes

All error codes returned by the mail-catcher API.

All error responses follow a consistent format:

{
  "error": "ERROR_CODE"
}

Error reference

Code	HTTP Status	Description	Endpoint
`UNAUTHORIZED`	`401`	Missing or invalid Bearer token	All protected endpoints
`NOT_FOUND`	`404`	Email or attachment not found	`GET /v1/emails/:id`, `DELETE /v1/emails/:id`, `GET /v1/emails/:id/raw`, `GET /v1/emails/:id/attachments/:file`
`MISSING_INBOX`	`400`	Required `inbox` parameter missing	`GET /v1/emails`, `DELETE /v1/emails`
`INVALID_INBOX`	`400`	Inbox contains invalid characters (valid: `a-z 0-9 . _ -`)	`GET /v1/emails`, `DELETE /v1/emails`
`INVALID_LIMIT`	`400`	`limit` is outside the `1`–`100` range	`GET /v1/emails`
`VALIDATION_ERROR`	`400`	Other parameter validation failure	`GET /v1/emails`

Status	Meaning
`200`	Success
`302`	Redirect to pre-signed S3 URL (raw email and attachment downloads)
`400`	Bad request, check the error code for details
`401`	Unauthorized, invalid or missing authentication
`404`	Resource not found

All 401 responses return the same UNAUTHORIZED code regardless of whether the token is missing, malformed, or invalid. This prevents token enumeration.
The VALIDATION_ERROR code is a catch-all for request validation issues not covered by the specific codes above.
Error responses never include stack traces or internal details.