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 on their endpoints above, 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 the emails or suppressions list issued.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.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.Limits, in one place:
Requests60 a minute per key and 600 a minute per account across its keys, every endpoint together, counted in memory on the server. Over either: 429 rate_limited.Daily sending500 recipients a day to begin with (dailyQuota on your account), reset at midnight UTC; a tenth of that, never below 20, while your rates grade as throttled. Over it: 429 quota_exceeded.CreditsOne per accepted message. At zero, sending continues for 3 days or 300 emails, whichever ends first, with a warning on every response; then 402 no_credits.RecipientsUp to 10 per send.BodyUnder 1 MB in all; subject up to 300 characters, html 500,000, text 100,000, 50 line items in a template.Sandbox1000 sandbox sends in any 24 hours.Listslimit from 1 to 100, default 25. nextCursor is null on the last page.Idempotency-Key1 to 255 characters; answers kept 24 hours; an unanswered claim is released after 15 seconds.Webhooks20 endpoints; 10 s to answer; 6 attempts; off after 10 consecutive failures; one test ping per endpoint every 10 s.Accounts200 sub-accounts, 50 live keys and 20 domains per account.