Errors and limits
#Every error is { "error": { "code": "...", "message": "..." } }. Branch on code; message is written for the person reading the log and may change. Four codes can come from any endpoint: 401 invalid_key, 403 insufficient_scope, 404 account_not_found (X-Barua-Account named something that is not yours) and 429 rate_limited. The rest are listed with the endpoints that answer them, and all of them here:
401 invalid_keyNo Authorization header, a token that does not start with barua_, or a key that was revoked.429 rate_limitedMore than 60 requests in a minute from this key, or more than 600 in a minute from all of the account's keys together, on any endpoints. Wait for the window to pass.403 insufficient_scopeThe key lacks the scope the endpoint needs, or tried to mint a key with a scope it does not hold itself.404 account_not_foundX-Barua-Account names something that is not a sub-account of this key's account. The same answer as for an id that does not exist.400 invalid_jsonThe request body could not be parsed as JSON.422 invalid_requestThe body or query failed validation. The message names the first field that failed.422 invalid_cursorcursor is not one this list issued: pass back the nextCursor it gave you, unchanged.400 invalid_idempotency_keyIdempotency-Key was sent but is empty or longer than 255 characters.413 body_too_largeThe request body is 1 MB or more.409 idempotency_in_progressThe first request with this Idempotency-Key is still running. Retry in a few seconds to get its answer.422 idempotency_mismatchThis Idempotency-Key was already used with a different body. Use a new key for each new email.403 suspendedSending is paused on the account this request acts for, or on its parent. The message is the reason, written for the sender; a parent's pause is prefixed with: The parent account cannot send.429 quota_exceededThe daily quota of the account, or of its parent, is used up. It resets at midnight UTC, which is 03:00 East Africa Time.429 sandbox_limitThe account has made 1000 sandbox sends in the last 24 hours.402 no_creditsThe paying account has no credits and its grace window has closed.403 domain_not_yoursThe from-address is on a domain this account has not connected.403 domain_not_readyThe domain is connected but its ownership record is not verified or sending is not yet enabled for it.422 recipient_suppressedOne or more recipients are on the suppression list. Nothing was sent; the message names them.502 send_failedBarua's mail server did not accept the message. The send is logged with status failed. Not filed under the Idempotency-Key, so a retry with the same key is a fresh attempt.404 email_not_foundNo email with that id on this account.404 not_foundNo domain, sub-account or key with that id on this account.409 domain_existsThe domain is already on this account.409 domain_unavailableThe name is claimed elsewhere and cannot be added here. Whether it belongs to another Barua account is deliberately not confirmed. A claim that was never verified and is more than a week old is cleared instead, and the name can be claimed.409 domain_limitThe account already has 20 domains.409 limit_reachedThe account already has 200 sub-accounts, or 50 live keys.409 domain_in_useThe domain still has active mailboxes. Remove them first.409 conflictA sub-account tried to open a sub-account, or a suspension cannot be lifted from the API: it was placed by Barua rather than through the API, or the sub-account's own bounce and complaint rates still grade as paused.404 suppression_not_foundThe address is not on this account's suppression list.503 not_configuredThe server cannot store secrets yet, so neither a webhook secret nor a database URL can be kept.422 invalid_urlThe URL cannot be used. A webhook URL must be https, carry no credentials and point at a public host that resolves. A database URL must be postgresql:// with a host and a user, and may not turn TLS off with sslmode=disable.422 too_many_endpointsThe account already has 20 webhook endpoints.404 webhook_not_foundNo webhook endpoint with that id on this account.429 ping_cooldownA test ping was sent to this endpoint in the last ten seconds.422 blocked_hostThe host resolves to a private, loopback or reserved address. Barua connects only to public hosts.422 database_unreachableBarua could not connect, log in, or create its schema there. The message says which.404 database_not_connectedNo database is set on this account.403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.404 machine_not_foundNo machine with that id was started by this key. Another key's machine answers the same, so ids cannot be probed.422 lifetime_out_of_rangeexpiresInMinutes is under the minimum, or would take the machine past the hour cap counted from when it started.409 machine_limit_reachedThis key, or this account, already has as many machines running as it may. Destroy one first.409 machine_budget_exhaustedThis machine would take the account past its machine-hours for the calendar month. A running machine counts until its end.409 machine_not_runningThe machine has already been destroyed, so it cannot be given more time.503 machines_at_capacityBarua is running as many machines as it is prepared to pay for at once. Try again later.503 machines_unavailableBarua's machine provider is not connected, so nothing can start.502 provider_errorThe provider refused to create the machine. Nothing is running or counted against the account; the message carries the provider's reason.404 advert_not_foundNo advert with that id on this account. Another account's advert answers the same, so ids cannot be probed.409 already_makingThe advert is being made, so it cannot be changed or made again until it is done or has failed.400 no_productThe advert's brief does not say what it is for (brief.product is empty).402 no_advert_creditsThe account's balance is under the price of one advert. Nothing was charged and the draft is kept.502 payment_failedThe charge for the advert could not be taken. Nothing was charged; try again.422 too_many_photosThe advert already has eight pictures, the most one advert can use.503 storage_unavailableFile storage is not configured on this deployment, so no upload link can be made.
Limits
On this page