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

# Errors

> When something goes wrong you get an HTTP status, a stable code to branch on, and a message to log or show.

## The error object

```json Response · 400 theme={null}
{
  "message": "Address is required",
  "status": "error",
  "statusCode": 400,
  "code": "invalid_request",
  "details": {
    "errors": ["Address is required", "Amount must be a positive number"]
  },
  "requestId": "req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b",
  "timestamp": "2026-11-04T10:00:00.000Z"
}
```

**message** `string`

What went wrong, written for people. It may be reworded, so don't match on it.

**code** `string`

A stable code to branch on. See the table below.

**statusCode** `integer`

The HTTP status.

**details** `object | null`

For validation errors, `details.errors` lists every problem; `message` is the first.

**requestId** `string`

Quote it when you contact us and we can find the request. It's also in the `X-Request-Id` header of every response.

## Codes

| Status | `code` | What to do |
| - | - | - |
| 400 | `invalid_request` | Fix the request. `details.errors` says what's wrong. |
| 401 | `authentication_failed` | Check the key: missing, mistyped or revoked. |
| 403 | `permission_denied` | The key can't do this, such as a live key on a sandbox endpoint. |
| 404 | `not_found` | Nothing of yours has that ID or reference. |
| 409 | `conflict` | The reference was used before. Look up the existing payment. |
| 429 | `rate_limited` | Slow down, then retry. See [Rate limits](https://docs.flipeet.io/rate-limits.md). |
| 500 | `internal_error` | Our fault. Retry with backoff; if it keeps happening, send us the request ID. |
| 502 | `provider_error` | A bank or network partner failed. Safe to retry with the same reference. |
| 503 | `service_unavailable` | Temporarily unavailable. Retry with backoff. |
| 504 | `provider_timeout` | A partner didn't answer in time. Check the payment's status before you retry. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.