Errors

The error format

An error comes back as JSON with an error object: code is fixed, so match on it; message says what went wrong in words, and may change.

{
  "error": {
    "code": "invalid_request",
    "message": "email is required"
  }
}

Codes

Every answer has an x-request-id header, and errors repeat it as request_id: send it to us if you need help with a call. A 5xx may come without the JSON body, such as when the request never reached the API, so don't count on one.

When to try again

• 429: wait for the seconds in Retry-After, then try again.
• 5xx: try again after a short wait, doubling it each time (1, 2, 4, then 8 seconds), and give up after a few tries.
• 400, 401 and 402: the same request will fail the same way. Log it and fix the cause.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function withRetries(send) {
  for (let attempt = 1; ; attempt++) {
    const res = await send();
    const retry = res.status === 429 || res.status >= 500;
    if (!retry || attempt === 5) return res;
    // Retry-After when we're told; otherwise 1, 2, 4, then 8 seconds.
    const seconds = Number(res.headers.get("Retry-After")) || 2 ** (attempt - 1);
    await sleep(seconds * 1000);
  }
}

import time

def with_retries(send):
    for attempt in range(1, 6):
        res = send()
        retry = res.status_code == 429 or res.status_code >= 500
        if not retry or attempt == 5:
            return res
        # Retry-After when we're told; otherwise 1, 2, 4, then 8 seconds.
        time.sleep(int(res.headers.get("Retry-After", 2 ** (attempt - 1))))

Pass withRetries (or with_retries) a function that makes the request, so each try sends it again.

Timeouts

A check asks another company's mail server, and some take up to a minute to answer. Give POST /verify and POST /find a client timeout of about 90 seconds; the examples on these pages do.

Be careful retrying POST /emails after a timeout: the send may have been accepted before the connection dropped. Send an Idempotency-Key header, and the same key sent again won't send the email twice.