Skip to main content
Every error from the Sentvia API comes with a standard HTTP status code and a structured JSON body. The body always includes an error string identifying the specific problem, and may include additional fields — like limit_bytes or upgrade — that tell you exactly what to do next.

​
Error shape

Example error body
{
  "error": "storage_limit_reached",
  "limit_bytes": 1073741824,
  "upgrade": true
}
The upgrade: true flag signals that the error is caused by a plan limit and can be resolved by upgrading — useful for surfacing an actionable prompt to users.

​
HTTP status codes

StatusMeaningNotes
400Bad requestA required field is missing or malformed.
401UnauthorizedMissing or invalid API key.
402Upgrade requiredA plan limit was hit (upgrade: true). See below.
404Not foundThe resource doesn’t exist or isn’t yours.
409Conflictaddress_taken — that inbox address is already in use.
413Payload too largeattachment_too_large — over the per-message size limit.
422Unprocessableno_deliverable_recipients — all recipients are suppressed or blocked.

​
Plan-limit errors (402)

The following errors carry upgrade: true and indicate you have reached a cap for your current plan:
errorTrigger
inbox_limit_reachedOver your plan’s inbox cap.
custom_domains_require_paid_planCustom domains require Pro or higher.
dedicated_subdomain_requires_scaleDedicated sending subdomains require Scale or higher.
storage_limit_reachedOver your attachment storage cap.

​
Recommendations

Follow these practices to handle errors cleanly and keep your agent reliable:
  • 401 — surface the key problem immediately. A missing or invalid API key is a configuration issue, not a transient error. Do not retry; surface the problem so it can be fixed.
  • 402 — treat it as actionable. Link the user or operator to the Billing page rather than failing silently. The upgrade: true field confirms an upgrade will resolve it.
  • Use idempotency keys on sends. Pass a client_id on every POST /messages call. If you retry after a network timeout, Sentvia deduplicates on client_id and never delivers the same message twice.
  • Verify webhook signatures and return 2xx fast. Sentvia retries delivery with exponential backoff on any non-2xx response. Verify the signature, enqueue processing, and acknowledge immediately to avoid duplicate deliveries.