# 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](https://usesendy.com/docs/smtp#smtp-idempotency-heading).

## 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](https://usesendy.com/docs/api/email-status).