API errors
Every error from the REST API (/api/v1) and the partner API (/api/partner) has the same shape:
{
"success": false,
"error": "This API key is missing the required scope: mail:send",
"code": "insufficient_scope",
"fix": "Create a key that includes the \"mail:send\" scope at https://faivelo.com/settings/developers and use it instead; scopes cannot be added to an existing key.",
"docs": "https://faivelo.com/docs/developers/errors#insufficient_scope",
"statusCode": 403
}
| Field | Meaning |
|---|---|
code | Stable, machine-readable. Branch on this, never on the message text. |
error | What went wrong, in plain English. May include specifics such as the scope or address. |
fix | What to change before trying again. |
docs | A link to the code's entry on this page. |
param | The request field at fault. Only on validation_error, and only when one field is to blame. |
statusCode | The HTTP status, repeated for convenience. |
Some errors carry extra fields, such as requiredScope on insufficient_scope and retryAfter (seconds) on rate_limited. A 429 also sets the Retry-After header.
Retry 429 after the wait it names, and 5xx with backoff. Send the same Idempotency-Key on a retried send and it goes out at most once. Every 4xx other than 429 fails the same way until the request or the account changes: read fix first.
The SDK (npm install faivelo) throws these as FaiveloError, with the HTTP status in statusCode and the message in message.
Authentication (401)
missing_api_key
401 · Send the key as "Authorization: Bearer fvl_live_..." (or an "X-API-Key" header). Keys start with fvl_live_; a person on the account creates one at https://faivelo.com/settings/developers.
invalid_api_key
401 · The key is unknown or was revoked. Check it was copied in full, or create a new key at https://faivelo.com/settings/developers.
api_key_expired
401 · Create a new key at https://faivelo.com/settings/developers and replace the expired one.
invalid_access_token
401 · The OAuth access token (fvl_oat_...) is invalid, expired or revoked. Refresh it with your refresh token, or reconnect the app.
unauthorized
401 · Authenticate with an API key in the Authorization header: "Bearer fvl_live_...".
Billing (402)
plan_required
402 · The account's plan does not include this. A person on the account can upgrade at https://faivelo.com/billing.
payment_required
402 · This costs money and the account has no card that can be charged. A person on the account opens "checkoutUrl" (in the error, when present) in a browser and pays, or adds a card at https://faivelo.com/billing; then repeat the request. Nothing was made or charged.
Permission and account state (403)
agent_inbox_only
403 · Labels and threads are part of Faivelo Agents: they work on agent inboxes (a free fvlmail.com address, or mailboxes on an Agents plan), not on a person's mailbox. See https://faivelo.com/ai-agents.
insufficient_scope
403 · The key does not carry the scope this endpoint needs (named in the error). Create a key with that scope at https://faivelo.com/settings/developers; scopes cannot be added to an existing key.
partner_key_not_allowed
403 · Partner keys only work on /api/partner/* endpoints. Use an account or agent key (fvl_live_...) for /api/v1.
account_paused
403 · The partner that manages this account paused it. The partner can resume it from the partner API or console.
account_suspended
403 · Retrying will not help. The account owner should contact support@faivelo.com.
sending_paused
403 · Sending is paused because recent mail bounced or was reported as spam. Retrying will not help; the account owner should read the email Faivelo sent them or contact support@faivelo.com.
phone_verification_required
403 · The account owner skipped the phone check at sign-up, so sending waits until they verify a phone number at https://faivelo.com/settings/security. Receiving works meanwhile.
send_limit_reached
403 · The plan's monthly send allowance is used up. Wait for the next billing month or upgrade at https://faivelo.com/billing.
domain_not_on_account
403 · Send from an address on a domain this account owns. List them with GET /api/v1/domains.
domain_not_verified
403 · The sending domain has not passed DNS verification yet. Add the DNS records shown for it in the dashboard (GET /api/v1/domains/{domain} returns its status), then retry once it is verified.
shared_domain_phone_required
403 · A person on the account must verify a phone number in the dashboard before this free address can send.
claim_required
403 · Until a person claims the account, it can only reply (5 a day) to people who wrote to the inbox first. Retrying will not help: give the claim_url from signup to the person you work for (POST /api/v1/account/claim issues a fresh link); once they sign in, sending opens up.
forbidden
403 · The key is valid but not allowed to do this. Check the key kind and scopes, or use a key from the account that owns the resource.
Request problems (400, 413)
validation_error
400 · A field in the request is missing or has the wrong type or format (named in "param" when known). Correct it and resend; the API reference at https://faivelo.com/docs/api lists every field.
invalid_sender
400 · Use a plain sender like "hello@yourdomain.com" or "Name hello@yourdomain.com" on a verified domain.
shared_label_invalid
400 · Pick another name (the error says what was wrong with this one): letters, digits and single dashes, not reading as another company. Or leave the name out and one is picked for you.
idempotency_key_invalid
400 · Send an Idempotency-Key of 256 characters or fewer, derived from the event that triggered the send (an order id, not a timestamp).
invalid_request
400 · The request was malformed. Check it against the API reference at https://faivelo.com/docs/api.
attachments_too_large
413 · Keep attachments to 25 MB in total. Files over ~3 MB must be uploaded first with POST /mailboxes/{address}/attachments, since a request body is capped at 4.5 MB. Otherwise send a link.
payload_too_large
413 · Send a smaller request body.
Not found (404)
mailbox_not_found
404 · Use the full address (user@yourdomain.com). GET /api/v1/mailboxes lists the mailboxes this key can reach; agent keys only see mailboxes they created or were granted.
domain_not_found
404 · GET /api/v1/domains lists the domains on this account. Use the bare domain, e.g. "yourdomain.com".
alias_not_found
404 · GET /api/v1/aliases lists the aliases on this account.
email_not_found
404 · Use the "id" returned by POST /api/v1/emails. Ids belong to the account that sent the email.
template_not_found
404 · Check the template alias in the dashboard under Transactional → Templates; aliases are case-sensitive.
service_not_found
404 · No service with that id on this account. List the account's services with GET /api/v1/services and use an "id" from there.
not_found
404 · The resource does not exist or this key cannot see it. Check the path against https://faivelo.com/docs/api.
Conflicts and refused content (409, 422)
idempotency_in_progress
409 · A request with the same Idempotency-Key is still running. Wait a few seconds and retry with the same key to get its result.
idempotency_key_reused
422 · This Idempotency-Key was already used with a different request body. Use a new key for a new request.
shared_label_taken
409 · Someone already holds that name. Choose another, or leave the name out and one is picked for you.
template_paused
409 · Resume the template in the dashboard under Transactional → Templates, or send inline html/text instead.
conflict
409 · The resource is in a state that does not allow this. Read it again, then retry.
missing_template_variables
422 · Pass every variable the template uses in "variables" (the missing names are in the error). Nothing was sent.
batch_too_large
422 · A bulk send may carry at most the plan's per-call cap in recipients (the error names it). Split the recipients across several calls with different idempotency keys, or upgrade at https://faivelo.com/billing for a larger cap. Nothing was queued.
all_recipients_suppressed
422 · Every recipient previously hard-bounced or reported spam, so nothing was sent. Remove them from the suppression list in the dashboard only if you are sure the address now works.
unprocessable
422 · The request was understood but could not be completed. The error says why.
Limits (429)
rate_limited
429 · Too many requests for this key (120 per minute). Wait for the Retry-After header (seconds), then retry.
signup_rate_limited
429 · Too many free inboxes were created from this network recently. Reuse the inbox you already have, or wait for the Retry-After header (seconds).
mailbox_creation_limit
429 · A key may create 10 mailboxes per rolling 24 hours. Reuse an existing mailbox or try again tomorrow.
mailbox_day_cap
429 · A partner may create 50 mailboxes per customer in a rolling 24 hours through the API. Mailboxes a bulk migration creates do not count. Create the rest tomorrow, or bring a whole domain over with a migration.
send_rate_limited
429 · The plan's sending speed or daily volume is used up. The error says which limit and when it resets; wait that long, or split the recipients across several calls.
shared_domain_send_limit
429 · Free shared addresses have a small daily send allowance. Wait until tomorrow, or send from your own domain on a paid plan.
Server (5xx)
send_failed
502 · The email could not be handed to the mail system. Retry with the same Idempotency-Key; it is safe and sends at most once.
internal_error
500 · Something went wrong on our side. Retry with backoff; if it persists, email support@faivelo.com with the time of the request.
Use Faivelo from your coding agent
One-command installs of the Faivelo MCP server and email skill for Claude Code, Cursor, Codex, VS Code, Gemini CLI, Windsurf and OpenClaw.
Email your agent
Give an AI agent its own address in two minutes, then talk to it by email. Works with Claude, ChatGPT and any agent that speaks MCP.