WoyraDocs
Get an API key

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.

CodeHTTPMeaning
authentication_required401The request carried no API key, or a console session that has expired.
invalid_api_key401A credential was presented and Woyra does not accept it.
insufficient_scope403The credential is valid but was not granted the scope the endpoint requires. The message names the scope.
invalid_request400The body or a parameter did not pass validation. The param field names the field at fault.
not_found404The id is unknown, or it belongs to another account.
idempotency_conflict409This Idempotency-Key was already used for a request whose body differed, so replaying it would be a lie.
idempotency_in_progress409A concurrent request holds this idempotency key. Woyra refuses rather than sending twice.
insufficient_funds402Woyra reserves the cost when a message is accepted, and the balance is short.
spend_cap_exceeded402You set a cap and this send would cross it, so it was refused.
route_unavailable503Every route for this destination is unavailable, or none fits the cost cap you set.
product_not_offered404The endpoint exists in the API but the product behind it is parked here.
domain_not_verified403The from address is on a domain this account has not proved it controls.
recipient_suppressed403This address or number has hard-bounced, complained, or opted out, so Woyra will not send to it again.
sending_paused403Too 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_reached402Without 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_reached429Each 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_limited429You crossed a rate limit. The Retry-After header says how long to wait.
mfa_required403A console session reached something that requires two-factor authentication before it is allowed.
mailbox_suspended409A Woyra Mail mailbox is suspended, so nobody can sign in to it and its existing tokens stop working. Its mail is kept.
resync_required410A Woyra Mail sync cursor was not one this mailbox issued, so changes cannot be resumed from it.
data_residency_violation451This data is resident in a region that this endpoint may not serve, so the request is refused rather than logged and permitted.
unsupported_version400The Woyra-Version header names a version this deployment does not know.
internal_error500An unhandled failure. Nothing was charged that should not have been: money moves in the same transaction as the record of it.