Error Handling

The Artmail API uses standard HTTP status codes and a consistent error format. Handling errors correctly improves reliability and helps you recover from transient failures.

HTTP Status Codes

Status	Code	Meaning
200	OK	Request succeeded (e.g. GET, PATCH).
201	Created	Resource created successfully (e.g. POST).
400	Bad Request	Invalid input, validation failed, or business rule violated.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Valid key but insufficient permissions or blocked (IP/domain).
404	Not Found	Resource does not exist (e.g. template slug, webhook).
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error; retry with backoff.

Error Response Format

All error responses use this structure:

Field	Type	Description
error	string	User-friendly error message.
code	string	Machine-readable code for programmatic handling.
details	any	Optional. Validation issues, suppressed emails, etc.

Example Error Responses

Validation error (400):

Rate limit (429):

Unauthorized (401):

Common Error Codes

Code	Status	Description
validation_error	400	Invalid request body or parameters. Check details.
sender_not_verified	400	Sender email/domain not verified.
recipient_suppressed	400	Recipient on suppression list (unsubscribed/bounced).
template_not_found	404	Template slug not found or template inactive.
missing_variables	400	Required template variables not provided.
INVALID_KEY	401	Missing, invalid, or expired API key.
EXPIRED	401	API key has expired.
PERMISSION_DENIED	403	API key lacks required permission.
IP_BLOCKED	403	Request from disallowed IP.
DOMAIN_BLOCKED	403	Request from disallowed domain.
RATE_LIMITED	429	Too many requests. Implement backoff.
internal_error	500	Server error. Retry with backoff.
queue_failed	500	Email could not be queued. Retry may help.

Retry Strategy

When to Retry

• 429 — Rate limit: wait and retry (see Rate Limits).
• 500 — Transient server error: retry with exponential backoff.
• 503 — Service unavailable: retry with backoff.

When Not to Retry

• 400 — Fix the request (validation, business rules).
• 401 — Fix API key or authentication.
• 403 — Fix permissions or restrictions.
• 404 — Resource doesn't exist; no retry will help.

Exponential Backoff Example (Node.js)

Rate Limit Errors (429)

When rate limited, the API returns 429 with these headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	0 when rate limited
X-RateLimit-Reset	Unix timestamp when the limit resets

Optionally, Retry-After may indicate seconds to wait. See rate limits →

Handling Errors in Your Code

Next Steps