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 response
{
  "error": "Email not found.",
  "code": "not_found"
}

Status codes

StatusMeaningWhat to do
200Success
201Resource created
202Accepted, work continues in the backgroundUsed for sending and for test events.
400Body is not valid JSONFix the request body.
401Missing, unknown or revoked API keyCheck the Authorization header.
403Key lacks the required permission, the sender domain is not verified, or the route does not existRead the code and the message.
404Resource not found in this workspaceCheck the id.
409Conflict, for example canceling an email that was already sentSee the message.
413Template variables larger than 256 KBSend less data.
422Validation failedSee the details field.
429Rate limit or monthly quota reachedWait for the time in Retry-After, or upgrade the plan.
503Health 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

CodeStatusMeaning
invalid_json400The body could not be parsed as JSON.
unauthorized401No valid API key or session.
missing_capability403The key lacks the permission named in the message.
no_route_policy403The path or method is not part of the API.
domain_not_found403The sender domain is not added to the workspace.
domain_not_verified403The sender domain has not passed the DNS check yet.
not_found404The resource does not exist in this workspace.
not_cancelable409Only scheduled emails can be canceled.
endpoint_disabled409A test event was requested for a paused webhook endpoint.
limit_reached409The workspace already has 20 webhook endpoints.
validation_error422One or more fields are invalid.
spam_check_failed422The pre-send spam check blocked the message. Only when the check runs in enforce mode.
rate_limited429Too many requests per second.
quota_exceeded429The 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.

422 response
{
  "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:

HeaderMeaning
RateLimit-LimitRequests allowed per second.
RateLimit-RemainingRequests left in the current second.
RateLimit-ResetSeconds until the limit resets.
X-Quota-LimitEmails included in the plan per month.
X-Quota-RemainingEmails left this month.