API reference
Errors and retries
Handle structured errors and distinguish a rejected request from uncertain provider acceptance.
Error format
Example error
{ "error": { "code": "domain_not_verified", "message": "The sending domain has not been verified." }}| Code | What to do |
|---|---|
invalid_api_key | Check the key, project and revocation state. |
production_not_enabled | Request operator review for live sending. |
domain_not_verified | Check the exact sender domain, DKIM and MAIL FROM. |
validation_error | Correct request fields; do not retry unchanged. |
message_too_large | Reduce the message below the size limit. |
idempotency_conflict | Use the original body for this key. |
quota_exceeded | Check the workspace allowance. |
rate_limit_exceeded | Back off before retrying the same operation. |
Request retries
After an API timeout, retry the identical body with the original Idempotency-Key. For an explicit validation or authorization error, fix the cause first. Read the existing message before deliberately creating another send.
Uncertain SES acceptance
These messages show failed with delivery_unknown and are never automatically resent. Check the provider before submitting a new copy. Authenticated provider events can later reconcile the outcome without resending.