Errors

When errors occur, the mail2many API returns an HTTP status code, an error code, and a readable message. This helps you diagnose and fix issues quickly.

HTTP status codes

Code	Meaning
200	OK — Request successful
201	Created — Resource created
204	No Content — Successful, no content returned
400	Bad Request — Invalid request
401	Unauthorized — Authentication failed
404	Not Found — Resource not found
409	Conflict — Resource already exists
422	Unprocessable Entity — Validation failed
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Server-side error

Error codes

Code	Title	Description
401	Invalid credentials	The API key is invalid or missing
1000	Unknown error	An unexpected error occurred
1001	Internal error	An internal API error occurred
1002	Validation failed	The provided data is invalid
1020	Error fetching resource	The resource could not be found
1021	Error creating resource	The resource could not be created
1022	Error updating resource	The resource could not be updated
1023	Error deleting resource	The resource could not be deleted
1024	Resource already exists	The resource already exists
1025	Resource is locked	The resource is locked and cannot be modified
1100	Too many failed authentications	The API key failed authentication too many times

Error response format

Error responses follow this format:

{
  "status": "error",
  "code": 1002,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email must be a valid email address."
    ],
    "firstname": [
      "The firstname must be a string."
    ]
  },
  "statusCode": 422
}

The errors field contains all invalid fields and their specific reasons.

Error handling flow

How to handle different types of errors:

API Request
    │
    ├─→ 200/201 ✓ Success
    │      └─→ Continue with next request
    │
    ├─→ 400/422 ✗ Validation error
    │      └─→ Check errors field
    │          └─→ Correct data
    │              └─→ Retry request
    │
    ├─→ 401 ✗ Authentication failed
    │      └─→ Check API key
    │          └─→ Use correct API key
    │              └─→ Retry request
    │
    ├─→ 404 ✗ Resource not found
    │      └─→ Check ID/parameters
    │          └─→ Use correct resource
    │
    ├─→ 429 ✗ Rate limit exceeded
    │      └─→ Check Retry-After header
    │          └─→ Wait X seconds
    │              └─→ Retry request
    │
    └─→ 500 ✗ Server error
           └─→ Exponential backoff
               ├─→ Attempt 1: after 1 second
               ├─→ Attempt 2: after 2 seconds
               ├─→ Attempt 3: after 4 seconds
               └─→ Maximum 3 attempts, then abort

Handling errors

• Check the response statusCode
• Read the message for a human-readable explanation
• For 1002 (validation): inspect errors to identify invalid fields
• For 401: verify your API key
• For 429: check Rate Limiting and reduce request rate or parallel requests
• Correct the data and retry the request

For endpoint-specific errors, refer to the documentation of the respective endpoint.