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

# Agent Loadout API Error Codes and HTTP Status Guide

> Every Agent Loadout API error returns JSON with an error object. Learn the HTTP status codes, error envelope format, and how to handle each case.

When a request fails, the API returns a JSON body with an `error` object alongside the appropriate HTTP status code. Every error response follows the same envelope — check `code` for a machine-readable identifier, `message` for a human-readable explanation, and `hint` for a suggested fix when one is available.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "This token does not have the email:send capability.",
    "hint": "Re-issue the token with email:send, or choose an agent token that already includes it."
  }
}
```

<ResponseField name="error.code" type="string">
  A short, stable identifier for the error type. Use this in code to branch on specific failures.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description of what went wrong.
</ResponseField>

<ResponseField name="error.hint" type="string" optional>
  A suggested action to resolve the error, when one is applicable.
</ResponseField>

## HTTP status codes

| Status | Meaning                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | **Bad request** — one or more parameters are missing, invalid, or out of range                    |
| `401`  | **Unauthorized** — the `Authorization` header is absent, malformed, or the token has been revoked |
| `402`  | **Payment required** — access is paused because a quota has been reached or a budget cap was hit  |
| `403`  | **Forbidden** — the token is valid but lacks the required capability for this action              |
| `404`  | **Not found** — the resource does not exist, or the token cannot see it                           |
| `409`  | **Conflict** — an idempotency key collision, or the requested state transition is not valid       |
| `429`  | **Too many requests** — the rate limit has been exceeded; back off and retry                      |

## Common scenarios and fixes

<Accordion title="401 Unauthorized">
  The `Authorization` header is missing, the token value is malformed, or the token has been revoked.

  **Fix:** Confirm the header is present and formatted as `Bearer <token>`. Open the agent's **Tokens** tab in the dashboard and verify the token is still active. If it was revoked, issue a new one.
</Accordion>

<Accordion title="403 Forbidden">
  The token is valid and the resource exists, but the token was not issued with the capability required by this endpoint — for example, trying to send mail with a token that only has `email:read`.

  **Fix:** Check which agent the token is bound to and which capabilities were granted at creation time. Either re-issue the token with the missing scope or use an existing token that already includes it.
</Accordion>

<Accordion title="402 Payment Required">
  A quota — outbound recipients, inbound messages, machine time, or mailbox storage — has been reached, or a spend cap has paused pay-as-you-go billing.

  **Fix:** Open **Billing & usage** in the dashboard. You may need to add agent seats, increase a spend cap, or wait for the monthly quota to reset.
</Accordion>

<Accordion title="409 Conflict on send">
  You sent a request with an `idempotency_key` that has already succeeded. The API will not re-process a key it has seen.

  **Fix:** The original result stands — check the response from the first call. Use the same `idempotency_key` when retrying a failed or timed-out request, and a **new** key when you intend to perform a distinct action.
</Accordion>

## Idempotency

The `send`, `reply`, and `create_machine` calls accept an optional `idempotency_key` string. If your request times out or you receive a network error before seeing a response, resend the exact same request body with the same `idempotency_key` — the API will return the original result instead of creating a duplicate.

<Note>
  Use a new, unique `idempotency_key` every time you intend a genuinely new action. Reusing a key for a different recipient or a different command is a logic error, not a retry.
</Note>

```bash title="Sending with an idempotency key" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/messages \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["person@example.com"],
    "subject": "Hello",
    "text": "Sent by my agent.",
    "idempotency_key": "outreach-run-42-msg-1"
  }'
```

## Rate limits

The `429` response includes a `Retry-After` header indicating how many seconds to wait before your next attempt. Implement exponential back-off for automated retry loops to avoid sustained rate-limit errors.