Error Codes

Error response shape

Sending refusals include success, error and detail:

{
  "success": false,
  "error":   "domain_not_verified",
  "detail":  "Domain 'acme.com' is not yet verified. Add both TXT ownership records, then press Verify all records at https://sendfleet.net/dashboard/domains/"
}

HTTP 400: Bad Request

Field validation failures return a map of field names to messages. A malformed JSON body can instead return a detail message. Check the status code and body before reaching for data.error.

{
  "to":          ["Enter a valid email address."],
  "attachments": ["File type '.exe' is not permitted for security reasons."]
}

Fix the listed fields. Do not retry without changing the request.

HTTP 403: API key rejected

The X-API-Key header is missing, or the key is invalid, revoked, or past its expiry date. This response carries no error code, so a bare 403 with no error field means the key was the problem rather than your account configuration.

{
  "detail": "Authentication credentials were not provided."
}

HTTP 403: Forbidden

The key is valid, but the account or domain configuration does not permit this send. Resolve the stated cause before retrying. A temporary pause or a plan change still being applied may clear without a configuration change.

HTTP 422: Unprocessable Entity

On Shared SES, the outcome arrives as an email.suppressed webhook and a suppressed status in your email logs. Treat that the same way you would have treated a 422: mark the address undeliverable on your side and stop sending to it. See Webhooks.

HTTP 429: Too Many Requests

Two different limits produce a 429, and they need opposite responses:

HTTP 500: Internal Server Error

An unexpected error on our side, returned with "error": "internal_error". These are rare. Retry once after a short backoff; if it persists, contact support with the approximate timestamp and the request you sent.

HTTP 502: Bad Gateway

HTTP 503: Service Unavailable

Error handling example

import time
import requests

# Fix-the-request errors. Retrying these unchanged will always fail again.
TERMINAL = {400, 403, 422, 503}
# Transient errors. Safe to retry with backoff.
RETRYABLE = {429, 500, 502}


def send_email(payload, retries=4):
    for attempt in range(retries):
        resp = requests.post(
            "https://api.sendfleet.net/v1/send",
            headers={"X-API-Key": "YOUR_KEY"},
            json=payload,
            timeout=10,
        )

        if resp.status_code == 200:
            return resp.json()

        data = resp.json()
        error_code = data.get("error")

        # A monthly quota 429 is terminal - no amount of waiting helps.
        if error_code == "usage_limit_exceeded":
            raise RuntimeError("Monthly quota exhausted - upgrade the plan.")

        if resp.status_code in TERMINAL:
            raise ValueError(f"[{error_code}] {data.get('detail')}")

        if resp.status_code in RETRYABLE:
            time.sleep(2 ** attempt)
            continue

        raise RuntimeError(f"Unexpected status {resp.status_code}")

    raise RuntimeError("Max retries exceeded")

Retry strategy reference