Errors

Handle HTTP request failures and SMTP responses.

HTTP errors

Email API failures return a JSON:API document with an errors array and the application/vnd.api+json content type. Each error includes a string status, a title, and a detail explanation. Use the HTTP status to decide what to do next:

409 Conflict · application/vnd.api+json

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Idempotency-Key was already used for a different email"
    }
  ]
}

400: Invalid email fields, an invalid or missing idempotency key, malformed JSON, or a sender domain that is not verified for this account.
401: Missing, invalid, or revoked API key.
402: Not enough available email credits to queue the message. Add credits before retrying; queued messages already reserve credits.
403: Your account is suspended or its contact email is unverified. Verify your email address or contact support before retrying.
404: The job does not exist or belongs to another account.
409: The idempotency key was already used for a different message.
413: The request body exceeds 256 KiB.
415: The request does not use application/vnd.api+json, or specifies unsupported media type parameters.
422: The JSON contains missing fields, unsupported fields, or values of the wrong type.
500: An internal error prevented the request from completing. Retry with the same idempotency key.
503: Sending is not configured or your sending account is still being set up.

SMTP responses

4xx: Temporary refusal. Retry after the cause is resolved; exhausted credits need a top-up.
5xx: Fix the credentials, message, or sender domain before retrying.

Specific submission responses include:

451 4.3.0: The sending account is not ready or the queue is temporarily unavailable. Retry later with the same idempotency key.
452 4.2.2: Not enough available email credits for all recipients. Add credits before retrying. The submission creates no jobs.
452 4.5.3: The transaction exceeds 50 distinct recipients. Split the recipient list into smaller transactions.
535 5.7.8: The API key is invalid or revoked. Use a valid key; retrying the same credentials does not resolve the failure.
554 5.5.0: The idempotency key was already used for a different email. Use the original message for a retry, or a new key for a separate email.
554 5.7.1: The account is suspended or the message or sender is invalid. Read the response text, correct the message or domain, or contact support.

A revoked API key cannot submit another message, even on an existing connection. Without an idempotency key, retrying after a lost final response can create duplicate jobs. A matching Sendy-Idempotency-Key retry returns the original job IDs. See SMTP idempotency requirements.

After a message is queued

Request errors and delivery errors are separate. After HTTP 202 or SMTP 250, inspect the job’s status and last_error with Get email status.