> ## Documentation Index
> Fetch the complete documentation index at: https://docs.12m.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes, error shapes, and when to retry.

Every error is JSON with at least an `error` field, optionally a
`details` object with structured context.

```json theme={null}
{ "error": "identity not found in org", "details": { "handle": "alice.acme@inboxbase.ai" } }
```

## 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

When `POST /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.                                          |

When the **whole request** is rejected (not just one recipient),
status is `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

<AccordionGroup>
  <Accordion title="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](https://inboxbase.ai/app/identities) and that the key
    prefix matches an active key in the same org.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://inboxbase.ai/app/identities) → the identity detail
    page shows current usage on a rolling graph.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Webhooks stop arriving">
    Three possibilities:

    1. **Endpoint paused.** Your URL returned `410 Gone`, or three
       consecutive failed deliveries triggered an automatic pause.
       Re-enable from the dashboard.
    2. **Secret rotated.** Your verifier is using the old secret and
       rejecting deliveries. Update your secret env var.
    3. **DNS / TLS.** The endpoint URL stopped resolving or its TLS
       certificate expired. Test with curl from outside your network.

    In all three cases your recovery path is the same: walk the
    [events stream](/api-reference/events) from the last `seq` you
    persisted to backfill missed events, then fix the underlying issue.
  </Accordion>
</AccordionGroup>