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

# Errors

> Understand the error response shape and decide when to retry.

Every `4xx` and `500` response (except `429`) is the same JSON object:

```json theme={null}
{
  "code": "insufficient_funds",
  "message": "The source account has $120.00 available but this transfer needs $500.00.",
  "details": {
    "available": "$120.00",
    "requested": "$500.00"
  },
  "referenceId": "4009-2alj5if"
}
```

| Field         | Use                                                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | Machine-readable reason. Branch on the HTTP status and this.                                                                                                                                      |
| `message`     | Human-readable context for an operator. Wording may become more specific over time; do not parse it.                                                                                              |
| `details`     | The values behind `message`, as strings keyed per `code` — for example the field that failed validation, or the amounts behind `insufficient_funds`. `{}` when the code carries no variable data. |
| `referenceId` | Uniquely identifies the failure on Slash's side. Include it when contacting support, especially about a `500`.                                                                                    |

## Errors every endpoint can return

These are raised at the boundary — authentication, request parsing, resource
lookup — before or around the operation itself, so every endpoint can return
them. Each reference page lists them alongside the endpoint's own codes,
grouped by status; this table is where they are explained once.

| Status | Code                    | When                                                                                                                                                                                                                                                                                                                                                                                    |
| ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`       | The body, query, or headers failed validation, or a required header such as `X-Idempotency-Key` is missing. `details` has one entry per failing location, keyed by JSON pointer (for example `/amount/amount`) or header name. Operations also use it for input that is well-formed but cannot be acted on, such as an expired FX quote; then `details.field` names the field at fault. |
| `401`  | `unauthorized`          | API key authentication is missing or invalid.                                                                                                                                                                                                                                                                                                                                           |
| `403`  | `forbidden`             | The credential can see the resource but is not permitted to perform this action on it. The missing permission is not disclosed. Also returned when the credential is scoped to another legal entity.                                                                                                                                                                                    |
| `403`  | `user_api_key_required` | The API key is scoped to a legal entity rather than a user. v2 only accepts [user API keys](/docs/v2/get-started/authentication).                                                                                                                                                                                                                                                       |
| `404`  | `not_found`             | No resource matches the identifier, it belongs to another legal entity, the credential cannot view it, or Public API v2 is not enabled for the selected legal entity. When the identifier is a field inside a request body (for example `destinationId` on a transfer), `details` names that `field` and the `id` it received.                                                          |
| `409`  | `conflict`              | A consumed `X-Idempotency-Key` was reused on an endpoint that takes one. The original response is not replayed; see [Idempotency](/docs/v2/get-started/idempotency).                                                                                                                                                                                                                    |
| `429`  | —                       | The caller exceeded an applicable rate limit. The body is plain text, not the object above.                                                                                                                                                                                                                                                                                             |
| `500`  | `internal`              | Slash could not complete the request.                                                                                                                                                                                                                                                                                                                                                   |

<Warning>
  `404 not_found` intentionally does not reveal whether a resource exists outside
  the caller's scope: a missing resource and one the credential cannot view are
  indistinguishable. `403 forbidden` is only returned for a resource the
  credential can already read.
</Warning>

## Errors specific to an endpoint

Anything an operation itself can refuse — insufficient funds, a state that
blocks a cancellation, a money-movement action that needs an IP allowlist —
is listed first under that status on the endpoint's reference page, with the
code and the message you will see. For example,
[Create an ACH transfer](/api-reference/transfers/ach/create) lists
`insufficient_funds` next to `conflict` under `409`, and
`ip_allowlist_required` next to `forbidden` under `403`. An endpoint never returns a code it does not list.

## Retry behavior

<CardGroup cols={2}>
  <Card title="Retry">
    Retry idempotent reads after `429` or `500` responses with exponential
    backoff and random jitter.
  </Card>

  <Card title="Fix before retrying">
    Change the request or credentials before retrying `400`, `401`, `403`, or
    `404` responses.
  </Card>
</CardGroup>

For a timed-out create request or a create request that returns `500`, do not
retry automatically. Its idempotency key may already be permanently consumed.
Follow the [idempotency guidance](/docs/v2/get-started/idempotency) and
reconcile through the resource's list and retrieve endpoints before deciding
whether to make a new create attempt.