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

> ## Agent Instructions
> If you are an AI assistant operating Infinite for a user, read the skill first: https://docs.infinite.dev/agent-skill.md (setup per host, tool reference, rules for moving money, journeys).
> When operating Infinite for a user, use the MCP server. Sign in at https://bot.api.infinite.dev/mcp (production, acts as the user) or send `Authorization: Bearer <key>` to https://bot.api.infinite.dev/mcp/sse. Prefer its tools over raw HTTP; use REST only for steps no tool covers, and check `get_endpoint_schema` before guessing a request shape.
> Net-new Infinite Connect (org_connect) is operator-assisted: do not grant end users shared org_connect Auth Kit membership or the shared platform org API key — those credentials are org-wide on /v1. BYO org keys onboard under that customer's org id. Operator sessions should show org_connect in get_organization_info.
> The key decides the tools. Every organization key (`sk_sandbox_…` / `sk_live_…`) gets docs, onboarding, `get_account_balance`, and request logs for your own organization. BYO organizations add payees an agent will pay with `create_payee` (payable once ACTIVE). Platform Connect sessions instead get bound-customer payment lookups (`get_quote`, `get_transfer`, `list_transfers`, `list_account_balances`), payee drafts (`create_payee_draft` / `get_payee_draft`; screening only, never payable), and transfer drafts that wait for Infinite approval (`create_transfer_draft` / `get_transfer_draft`; never POST /v1/transfers). Where offered, platform `create_transfer` files a real transfer that Infinite holds in review before funding; it cannot be submitted from DRAFT.
> An agent key (`sk_sandbox_agent_…` / `sk_live_agent_…`) moves money within that agent's limits: `create_transfer` → `submit_transfer` → `wait_for_transfer`.
> On sandbox organization-key sessions, `sandbox_approve_customer` (makes the capabilities you pass READY, and related ones may turn READY too; `request_capabilities` is not needed), `sandbox_fund_account`, and `sandbox_complete_transfer` stand in for verification, funding, and settlement, so a whole flow runs from MCP. BYO keys can pass `customerId` on each call without binding; platform sessions must bind a customer first (`create_business_customer` auto-binds, or send `X-Infinite-On-Behalf-Of`).
> When searching documentation without a key, use the docs MCP at https://docs.infinite.dev/mcp.
> Start in sandbox (https://sandbox.api.infinite.dev). Do not use production unless the user explicitly asks.
> Confirm amount, currency, and payee with the user before any payment is submitted. Pass the invoice number as `reference` on `create_transfer`; the summary says what the payee will see.
> REST amounts are integer minor units (`"4000"` = 40.00 USD). MCP payment tools take exact decimal strings (`"40.00"`). Never mix them.
> Agent denials return `403 { denial: { code, message, window, limit, used, remaining, attemptedAmount, currency }, hint }` with decimal amounts; per-transfer denials omit `used` and `remaining`. Report them to the user; do not work around them.

# Error handling

Proper error handling is crucial for building robust integrations with the Infinite API. This guide covers error types, best practices, and recovery strategies.

## Error Response Format

All API errors follow a consistent JSON format:

```json theme={null}
{
  "error": "ValidationError",
  "message": "Invalid request parameters",
  "statusCode": 400,
  "details": [
    {
      "field": "email",
      "message": "Invalid email format",
      "value": "invalid-email"
    },
    {
      "field": "amount",
      "message": "Amount must be greater than 0",
      "value": -100
    }
  ],
  "requestId": "req_1234567890abcdef"
}
```

### Error Fields

* `error` - Error type/category
* `message` - Human-readable error description
* `statusCode` - HTTP status code
* `details` - Array of field-specific validation errors (when applicable)
* `requestId` - Unique request identifier for debugging

## HTTP Status Codes

Infinite uses standard HTTP status codes to indicate success or failure:

### 2xx Success

| Code | Description |
| - | - |
| `200` | OK - Request succeeded |
| `201` | Created - Resource created successfully |
| `202` | Accepted - Request accepted for processing |

### 4xx Client Errors

| Code | Error Type | Description |
| - | - | - |
| `400` | `BadRequestError` | Invalid request format or parameters |
| `401` | `UnauthorizedError` | Invalid or missing API key |
| `403` | `ForbiddenError` | Insufficient permissions |
| `404` | `NotFoundError` | Resource not found |
| `409` | `ConflictError` | Resource conflict (duplicate, etc.) |
| `422` | `ValidationError` | Request validation failed |
| `429` | `RateLimitError` | Too many requests |

### 5xx Server Errors

| Code | Error Type | Description |
| - | - | - |
| `500` | `InternalServerError` | Server error |
| `502` | `BadGatewayError` | Upstream service error |
| `503` | `ServiceUnavailableError` | Service temporarily unavailable |
| `504` | `GatewayTimeoutError` | Request timeout |


## Related topics

- [Idempotency](/guides/idempotency.md)
- [Webhooks](/guides/webhooks.md)
- [Introduction](/api-reference/introduction.md)
- [Initiate a new verification](/api-reference/verification/initiate-a-new-verification.md)
- [MCP Server](/guides/mcp.md)