Errors

The Emailit API uses HTTP status codes to tell you whether a request worked. Codes in the 2xx range mean success, 4xx codes mean something about the request needs to change, and 5xx codes mean something went wrong on our side. This page describes the error bodies, every status code the API returns and how to fix the most common errors.

Error response formats

Every error body is a JSON object with an error field. The exact shape depends on where the request failed. Write your error handling to read error, then message when it’s present, then any extra fields the endpoint documents.

Request errors

Authentication failures, permission errors, malformed JSON and other errors raised before an endpoint runs use the standard HTTP error format:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}

Validation errors

When a query parameter or body field has the wrong type, is missing, or is out of range, the API rejects the request with 400 before it runs and lists each problem in details:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}

instancePath points to the field (/limit, /to, /attachments/0/filename), and message describes the rule it broke. On a few endpoints, such as Send an email, these errors return only {"error": "Bad Request"}.

Resource errors

Errors raised by an endpoint, such as a missing object or a duplicate name, return error and often message:

{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}

Some errors add fields that help you recover:

Send validation errors

Send an email and Forward an email check the whole message at once and return every problem in validation_errors:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}

Field errors

Templates, campaigns and automations return validation problems grouped by field:

{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}

Rate limit errors

429 responses from the sending endpoints include the limit you hit and how long to wait. See Rate limits.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}

HTTP status codes

Common errors and how to fix them

Retry safely

• Retry 429, 500 and 503 responses after a delay. Use the retry-after header when it’s present, and exponential backoff otherwise. Rate limits has example code.
• Don’t retry other 4xx errors unchanged. They fail the same way until you fix the request.
• When you retry a send after a timeout or a 5xx error, reuse the same Idempotency-Key so the email isn’t sent twice.

Related