> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augustus.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.
# Errors
> The 2026-05-01 API returns consistent, structured error responses with machine-readable codes for programmatic handling.
## Error response
All errors return a flat JSON object with every field always present:
Broad error classification. One of: `api_error`, `authentication_error`, `idempotency_error`, `invalid_request_error`, `rate_limit_error`.
Machine-readable error code for programmatic handling. Use this to branch on specific error conditions. Never parse the `message` field.
Human-readable description of the error. Not a stable contract. Do not parse or branch on message content.
The request parameter that caused the error, or `null` if not parameter-specific.
Link to documentation explaining the error.
Unique request identifier for tracing and support. Also returned as a `Correlation-Id` response header on all responses.
## Categories
| Category | Meaning |
| ----------------------- | --------------------------------------------------------------- |
| `api_error` | Server-side failure. You did nothing wrong. Retry may help. |
| `authentication_error` | Missing or invalid API key. |
| `idempotency_error` | Idempotency key conflict (reuse with different params). |
| `invalid_request_error` | Client-side problem: bad parameters, not found, state conflict. |
| `rate_limit_error` | Too many requests. Back off and retry. |
## Error codes
### Structural codes
| Code | Category | HTTP | When |
| ------------------------------ | ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| `parameter_invalid` | `invalid_request_error` | 400 | Request parameter fails validation |
| `parameter_missing` | `invalid_request_error` | 400 | Required parameter not provided |
| `validation_error` | `invalid_request_error` | 400 | Request body fails schema validation |
| `api_version_error` | `invalid_request_error` | 400 | Unknown or unsupported `api-version` header value |
| `invalid_cursor` | `invalid_request_error` | 400 | Pagination cursor is malformed or could not be read |
| `cursor_mismatch` | `invalid_request_error` | 400 | Pagination cursor was issued for different filters |
| `idempotency_key_required` | `invalid_request_error` | 400 | POST request sent without an [`Idempotency-Key`](/v1/idempotency) header |
| `authentication_required` | `authentication_error` | 401 | Missing or invalid API key |
| `permission_denied` | `invalid_request_error` | 403 | Valid key, but the request is forbidden by a non-scope check (feature flag, enabled surface, beneficiary allowlist) |
| `insufficient_scope` | `invalid_request_error` | 403 | Valid key, but missing one or more [scopes](/v1/scopes) the endpoint requires. Carries an additional `required_scopes` array |
| `resource_not_found` | `invalid_request_error` | 404 | Resource does not exist |
| `method_not_allowed` | `invalid_request_error` | 405 | HTTP method not supported on this endpoint |
| `conflict` | `invalid_request_error` | 409 | Business state conflict |
| `idempotency_key_already_used` | `idempotency_error` | 409 | Key reuse with different parameters |
| `request_in_progress` | `idempotency_error` | 409 | Concurrent request with same key |
| `payload_too_large` | `invalid_request_error` | 413 | Request body exceeds the maximum size |
| `rate_limit_exceeded` | `rate_limit_error` | 429 | Too many requests |
| `internal_error` | `api_error` | 500 | Unexpected server failure |
| `upstream_error` | `api_error` | 500 | A required upstream service returned an error |
### Domain codes
These codes refine `invalid_request_error` for specific resources. They allow finer-grained handling than the generic `parameter_invalid` or `validation_error`.
| Code | HTTP | When |
| --------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- |
| `payout_validation_failed` | 400 | Payout request fails business validation |
| `conversion_validation_failed` | 400 | Conversion request fails business validation |
| `quote_validation_failed` | 400 | Quote request fails business validation |
| `invalid_currency` | 400 | Currency is not supported for the requested action |
| `account_holder_already_existing` | 409 | An account holder with the same identity already exists. Carries an additional `existing_holder_id` field |
## Examples
```json 400 Validation theme={null}
{
"category": "invalid_request_error",
"code": "parameter_missing",
"message": "The amount parameter is required.",
"param": "amount",
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
```json 403 Insufficient scope theme={null}
{
"category": "invalid_request_error",
"code": "insufficient_scope",
"message": "Insufficient scope to perform this operation.",
"param": null,
"required_scopes": ["payouts:write"],
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "e5f6a7b8-c9d0-1234-ef01-234567890123"
}
```
```json 404 Not found theme={null}
{
"category": "invalid_request_error",
"code": "resource_not_found",
"message": "No payout found with the given ID.",
"param": null,
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
```
```json 409 Idempotency conflict theme={null}
{
"category": "idempotency_error",
"code": "idempotency_key_already_used",
"message": "This idempotency key has already been used with different parameters.",
"param": null,
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```
```json 429 Rate limited theme={null}
{
"category": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after a short delay.",
"param": null,
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "d4e5f6a7-b8c9-0123-def0-456789012345"
}
```
```json 500 Server error theme={null}
{
"category": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred. Please retry or contact support.",
"param": null,
"doc_url": "https://docs.augustus.com/v1/errors",
"correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}
```