Error codes
Every error response carries a doc_url pointing at one of these pages, so the thing your logs show is one click from the thing that fixes it.
Branch on code, never on message: the message is written for a human and may be reworded. When the fault is in a field, param names it.
| Code | HTTP | Meaning |
|---|---|---|
| authentication_required | 401 | The request carried no API key, or a console session that has expired. |
| invalid_api_key | 401 | A credential was presented and Woyra does not accept it. |
| insufficient_scope | 403 | The credential is valid but was not granted the scope the endpoint requires. The message names the scope. |
| invalid_request | 400 | The body or a parameter did not pass validation. The param field names the field at fault. |
| not_found | 404 | The id is unknown, or it belongs to another account. |
| idempotency_conflict | 409 | This Idempotency-Key was already used for a request whose body differed, so replaying it would be a lie. |
| idempotency_in_progress | 409 | A concurrent request holds this idempotency key. Woyra refuses rather than sending twice. |
| insufficient_funds | 402 | Woyra reserves the cost when a message is accepted, and the balance is short. |
| spend_cap_exceeded | 402 | You set a cap and this send would cross it, so it was refused. |
| route_unavailable | 503 | Every route for this destination is unavailable, or none fits the cost cap you set. |
| product_not_offered | 404 | The endpoint exists in the API but the product behind it is parked here. |
| domain_not_verified | 403 | The from address is on a domain this account has not proved it controls. |
| recipient_suppressed | 403 | This address or number has hard-bounced, complained, or opted out, so Woyra will not send to it again. |
| sending_paused | 403 | Too much of this account’s recent mail bounced or was reported as spam, or a Woyra operator paused it. Nothing more is sent until someone at Woyra has looked. |
| email_limit_reached | 402 | Without an email plan an account sends 1,000 emails a month free and nothing past them. On a plan it sends the plan’s emails each billing month, and past them only with overage on. |
| daily_send_limit_reached | 429 | Each account has a daily email limit that grows with its age: 200 on the first day, 1,000 in the first week, 5,000 in the first month and 20,000 after that. Mailboxes and the API count together. |
| rate_limited | 429 | You crossed a rate limit. The Retry-After header says how long to wait. |
| mfa_required | 403 | A console session reached something that requires two-factor authentication before it is allowed. |
| mailbox_suspended | 409 | A Woyra Mail mailbox is suspended, so nobody can sign in to it and its existing tokens stop working. Its mail is kept. |
| resync_required | 410 | A Woyra Mail sync cursor was not one this mailbox issued, so changes cannot be resumed from it. |
| data_residency_violation | 451 | This data is resident in a region that this endpoint may not serve, so the request is refused rather than logged and permitted. |
| unsupported_version | 400 | The Woyra-Version header names a version this deployment does not know. |
| internal_error | 500 | An unhandled failure. Nothing was charged that should not have been: money moves in the same transaction as the record of it. |