Error Codes

Response shape

Every error response from the API follows the RFC 9457 Problem Details format (the 2023 update to RFC 7807, with the same wire format and clarified semantics). The shape is consistent across every endpoint, every error class, every HTTP method — you write one error handler in your client and it works everywhere.

The five RFC 9457 fields (type, title, status, detail, instance) are always present. Three extension fields matter operationally:

• code — the machine-readable application error identifier. This is what your code branches on, not the human-readable title. title can change between releases for clarity; code is part of the API contract and is stable.
• request_id — unique identifier for this specific request. Always include this when contacting support — it lets us find the exact log entry for the failure in milliseconds rather than searching by timestamp.
• errors array — for validation errors, the API returns every validation problem at once, not the first one it found. A request with three invalid fields produces one response listing all three, not three round-trips fixing one field at a time.

HTTP status codes

The status code communicates the category of failure. The code field disambiguates within a category. As a rule, the status code tells you who needs to fix the problem; the application code tells you what to fix.

Application error codes

The code field in the response identifies the specific problem. These codes are stable across API versions; messages and titles may evolve, but the codes are the contract. Branch on these in your error handlers, not on the human-readable strings.

SMTP error codes (delivery events)

SMTP error codes are what receiving mail servers return when our PowerMTA infrastructure attempts delivery. These are not API errors — they show up in webhook delivery events (message.bounced, message.deferred) as the smtp_code and smtp_status fields. Understanding them is core operational literacy because they tell you exactly why an individual message failed and what to do about it.

The structure follows RFC 3463: a three-digit code (the legacy SMTP code, e.g. 550) plus an enhanced status of the form X.Y.Z (e.g. 5.1.1). The first digit of the code is the most important: 4xx is temporary, 5xx is permanent.

4xx codes — soft bounces (transient, retryable)

5xx codes — hard bounces (permanent, suppression triggered)

Retry decision matrix

The single most useful diagnostic table in this document. For each error class, this is whether retrying makes sense and under what strategy. Hardcoding this matrix into your error handler eliminates the most common cause of cascading failures: retrying things that will never succeed.

Idempotency keys

Network failures during retry can produce duplicate side effects unless the API supports idempotency. Send a charge twice; charge twice. Send a transactional email twice; deliver twice. The pattern that prevents this is the idempotency key: a client-generated identifier that the server uses to deduplicate requests.

The Cloud Server for Email API supports the Idempotency-Key header on every state-changing endpoint (POST, DELETE). Generate a key per logical operation, store it client-side, and include it on the request and any retry. The server caches the response for 24 hours; any retry with the same key returns the cached response without producing a duplicate effect.

Three rules for using idempotency keys correctly:

• One key per logical operation. The same payment attempt, the same password reset, the same notification — one key. A new operation gets a new key.
• Keys must be unpredictable to attackers. A UUID v4 is the standard choice. Sequential or guessable keys are a security problem.
• Send the same request body on retry. If the server sees the same key with a different body, it returns 409 Conflict (duplicate_idempotency_key). The semantics are: same key + same body = idempotent retry; same key + different body = client bug.

Worked examples

Two complete error scenarios and the correct client response to each. The same patterns apply across the rest of the error space.

Validation error: invalid recipient

You POST a message with an invalid to address.

Correct response: Do not retry. The status is 422, the code is invalid_email_address, and the field is to. Fix the address upstream (validate at form-submission time, not at send time) or skip this recipient. Logging the request_id makes troubleshooting easier if the same address shows up again.

Transient server error: 503 Service Unavailable

You POST a message during a brief queue overload.

Correct response: Wait 5 seconds (or however the Retry-After header indicates), then retry with the same Idempotency-Key from the original request. Cap retries at 5; if all fail, surface the error to the caller and do not silently drop the request.

Common pitfalls

Patterns that recur in production incidents and support tickets. Each is preventable; each is preventable in less code than you think.

• Branching on the human-readable message instead of the code. The title and detail fields are for humans; they may be reworded between releases. Branch on the code field, which is contract.
• Treating all 4xx as retryable. Only 429 in the 4xx range is retryable. Retrying 401 produces a lockout. Retrying 422 produces the same validation failure forever. Retrying 404 confirms that the resource still does not exist.
• Treating 5xx as a permanent failure. Server-side errors are usually transient. Backoff with jitter and retry up to 5 times before surfacing the error.
• Not capturing the request_id. When you contact support about a failure, the first thing we ask for is the request_id. If you have not logged it, the support call gets longer.
• Polling for retry timing instead of reading Retry-After. The header tells you exactly how long to wait. Polling at fixed intervals during a throttle wastes rate-limit budget you would rather use on real requests.
• Dropping errors silently. When the retry cap is exhausted, surface the error to the caller. Silent drops produce silent data loss; the caller needs to know that the operation did not complete so they can decide what to do.
• Implementing custom error formats instead of using the response shape. The Problem Details format is consistent across every endpoint. Building a custom error wrapper around it complicates testing without adding value. Trust the format.
• Using the same idempotency key across distinct operations. The key identifies one logical operation. Reusing it returns a cached response from the prior operation, which is rarely what you intended.
• Skipping idempotency keys on transactional sends. The cost of an idempotency key is a UUID; the cost of a duplicate transactional email is a customer support ticket. Use them.