error field, optionally a
details object with structured context.
Status codes
| Status | Meaning |
|---|---|
400 | Validation error: bad body shape, mutually-exclusive fields, malformed Idempotency-Key. |
401 | Missing or invalid API key. |
404 | Identity or conversation not in this org. |
409 | Idempotency-Key reused with a different body. |
429 | Daily cap exhausted, or all backing mailboxes capped/unhealthy. |
5xx | Server error. Retry with backoff + Idempotency-Key. |
Send rejection reasons
WhenPOST /send returns 200 with rejected recipients, each rejected
entry includes a reason. These are the values you may see:
reason | What happened |
|---|---|
cap_exceeded | The identity’s daily cap is exhausted. Wait until midnight UTC, or move the lead to another identity. |
no_accounts | All backing mailboxes are at their per-mailbox cap or below the health threshold. |
inactive | The identity is not currently in active state. Most often “still provisioning.” |
suspended | The identity is administratively suspended. Contact support. |
429 and the body has the same shape with accepted: 0.
Retry guidance
| Status | Retry? | How |
|---|---|---|
400 | No | Fix the body shape and try again. |
401 | No | Fix the auth header. |
404 | No | Verify the identity handle / convId. |
409 | No | Either reuse the original Idempotency-Key with the original body, or send with a new key. |
429 | Later | Don’t tight-loop. Reschedule the send for after midnight UTC, or to a different identity. |
5xx | Yes | Exponential backoff. Use the same Idempotency-Key so the retry is safe even if the original succeeded. |
Common errors and fixes
404 identity not found in org
404 identity not found in org
Most often a typo in the handle, or the request was made with a key
from a different org. Confirm the handle in
Dashboard → Identities and that the key
prefix matches an active key in the same org.
409 Idempotency-Key reuse
409 Idempotency-Key reuse
The same key was used with a different body. Either you actually meant
to send a different message — in which case use a new key — or the
retry that triggered this is using a slightly different body (often a
reformatted timestamp or a re-rendered template). Make the body
deterministic for retries.
429 cap_exceeded on a fresh-looking identity
429 cap_exceeded on a fresh-looking identity
Daily caps are per-identity, set by tier, and reset at midnight UTC. A
Starter tier identity is capped at 150/day. Check
Dashboard → Identities → the identity detail
page shows current usage on a rolling graph.
429 no_accounts
429 no_accounts
Every backing mailbox is either at its per-mailbox daily cap or has
dropped below the health threshold. This usually means the identity is
pulling more than its tier supports — bumping tier provisions more
mailboxes. If health is the issue, the dashboard will surface it on
the identity detail page.
Webhooks stop arriving
Webhooks stop arriving
Three possibilities:
- Endpoint paused. Your URL returned
410 Gone, or three consecutive failed deliveries triggered an automatic pause. Re-enable from the dashboard. - Secret rotated. Your verifier is using the old secret and rejecting deliveries. Update your secret env var.
- DNS / TLS. The endpoint URL stopped resolving or its TLS certificate expired. Test with curl from outside your network.
seq you
persisted to backfill missed events, then fix the underlying issue.