Error Codes

Every error from the SendFleet API follows a consistent shape. Use the machine-readable error field to branch your error-handling logic; use detail to log or surface a human-readable message.

Error response shape

All non-2xx responses (and some 400-level responses) return a JSON body.

{
  "success": false,
  "error":   "domain_not_verified",
  "detail":  "Domain 'acme.com' is not yet verified by SES. Add the TXT record and click Verify in the dashboard."
}

HTTP 400 - Bad Request

The request body is malformed, missing required fields, or contains invalid values. The response contains field-level validation errors.

{
  "to":      ["Enter a valid email address."],
  "message": ["This field may not be blank."]
}

Fix the fields listed in the response. Do not retry without modifying the request.

HTTP 401 - Unauthorized

The X-API-Key header is missing, the key is invalid, the key has been revoked, or the key has expired.

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

HTTP 403 - Forbidden

The API key is valid but the account or domain configuration prevents sending. These errors require action in the dashboard - retrying the same request will always fail.

HTTP 422 - Unprocessable Entity

HTTP 429 - Too Many Requests

Two distinct rate limits can produce a 429:

HTTP 502 - Bad Gateway

HTTP 503 - Service Unavailable

HTTP 500 - Internal Server Error

An unexpected error on our end. These are rare. Retry once with exponential backoff. If the error persists, contact support with the approximate timestamp and your request details.

Retry strategy reference

Error handling example

import requests, time

def send_email(payload, retries=3):
    for attempt in range(retries):
        resp = requests.post(
            "https://sendfleet.net/api/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")

        # Non-retryable errors - fix and stop
        if resp.status_code in (400, 401, 403, 422):
            raise ValueError(f"[{error_code}] {data.get('detail')}")

        # Usage limit - upgrade plan
        if error_code == "usage_limit_exceeded":
            raise RuntimeError("Monthly quota exhausted")

        # Retryable - backoff and retry
        if resp.status_code in (429, 502, 500):
            time.sleep(2 ** attempt)
            continue

        break

    raise RuntimeError("Max retries exceeded")