Errors and limits
The error format, status codes, error codes and rate limits used by every endpoint.
Error format
Errors are JSON with a sentence in error that says what went wrong and a stable code your program can branch on. Some errors add details. Successful responses never contain an error field.
The endpoints for domains, API keys, templates and automations do not send a code for every error yet. When it is absent, go by the HTTP status.
{
"error": "Email not found.",
"code": "not_found"
}Status codes
| Status | Meaning | What to do |
|---|---|---|
200 | Success | |
201 | Resource created | |
202 | Accepted, work continues in the background | Used for sending and for test events. |
400 | Body is not valid JSON | Fix the request body. |
401 | Missing, unknown or revoked API key | Check the Authorization header. |
403 | Key lacks the required permission, the sender domain is not verified, or the route does not exist | Read the code and the message. |
404 | Resource not found in this workspace | Check the id. |
409 | Conflict, for example canceling an email that was already sent | See the message. |
413 | Template variables larger than 256 KB | Send less data. |
422 | Validation failed | See the details field. |
429 | Rate limit or monthly quota reached | Wait for the time in Retry-After, or upgrade the plan. |
503 | Health check failed (database unreachable) | Only returned by /api/health. |
MailForge denies unknown routes by default. A request to a path or method that is not part of the API returns 403 with the code no_route_policy instead of 404.
Error codes
| Code | Status | Meaning |
|---|---|---|
invalid_json | 400 | The body could not be parsed as JSON. |
unauthorized | 401 | No valid API key or session. |
missing_capability | 403 | The key lacks the permission named in the message. |
no_route_policy | 403 | The path or method is not part of the API. |
domain_not_found | 403 | The sender domain is not added to the workspace. |
domain_not_verified | 403 | The sender domain has not passed the DNS check yet. |
not_found | 404 | The resource does not exist in this workspace. |
not_cancelable | 409 | Only scheduled emails can be canceled. |
endpoint_disabled | 409 | A test event was requested for a paused webhook endpoint. |
limit_reached | 409 | The workspace already has 20 webhook endpoints. |
validation_error | 422 | One or more fields are invalid. |
spam_check_failed | 422 | The pre-send spam check blocked the message. Only when the check runs in enforce mode. |
rate_limited | 429 | Too many requests per second. |
quota_exceeded | 429 | The monthly email quota of the plan is used up. |
Endpoints for templates, API keys and domains use further codes such as alias_taken. They are listed on the pages of those endpoints.
Validation errors
A 422 response names the first problem in error and lists all of them per field in details.
{
"error": "to: Must be a valid address like 'user@example.com' or 'Name <user@example.com>'.",
"code": "validation_error",
"details": {
"to": ["Must be a valid address like 'user@example.com' or 'Name <user@example.com>'."],
"subject": ["Too small: expected string to have >=1 characters"],
"html": ["Either 'html' or 'text' body must be provided."]
}
}Rate limit and quota
Each workspace may make 100 sending requests per second. A batch of 100 emails counts as one request. Above the limit the API answers 429 with the code rate_limited and a Retry-After header in seconds. Operators can change the limit with MAILFORGE_RATE_LIMIT_PER_SEC.
Every response to a send request carries these headers:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed per second. |
RateLimit-Remaining | Requests left in the current second. |
RateLimit-Reset | Seconds until the limit resets. |
X-Quota-Limit | Emails included in the plan per month. |
X-Quota-Remaining | Emails left this month. |