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

# Errors

> Every error code the API answers, and what to do about it.

Errors are JSON. Branch on the code — in `message` for most errors, in `code` when the body has one. Never branch on the human text. See [Conventions](/conventions#errors).

| HTTP | Code | What to do |
| - | - | - |
| 400 Bad Request | `(validation messages)` | Fix the request. `message` is a list of what is wrong. |
| 401 Unauthorized | `AUTHENTICATION_FAILED` | Check the `X-API-Key` header and that the key is active. |
| 403 Forbidden | `SCOPE_REQUIRED` | Your key lacks the endpoint's scope. Ask Rampa. |
| 404 Not Found | `ACCOUNT_NOT_FOUND` | No account with that id for your key. |
| 409 Conflict | `IDEMPOTENCY_CONFLICT` | That Idempotency-Key was already used with a different request. |
| 422 Unprocessable Entity | `AMOUNT_INVALID` | Not a positive amount with at most 2 decimals. |
| 422 Unprocessable Entity | `FAUCET_LIMIT_EXCEEDED` | Over 100.00 for one request (limit: per\_request, with max\_amount). |
| 422 Unprocessable Entity | `FAUCET_ADDRESS_IS_OURS` | That is a Rampa address, e.g. your top-up address. Use your own wallet. |
| 429 Too Many Requests | `FAUCET_LIMIT_EXCEEDED` | Cooldown, your daily limit, the per-address limit or the shared daily total. limit says which; retry\_after\_seconds or remaining when it helps. |
| 502 Bad Gateway | `FAUCET_SEND_FAILED` | Refused before anything was sent. Nothing counted against your limits; try again later. |
| 502 Bad Gateway | `FAUCET_SEND_UNCONFIRMED` | We could not confirm the send. Retry with the SAME Idempotency-Key: it never sends twice. |
| 503 Service Unavailable | `FAUCET_EMPTY` | The faucet is out of test tokens. Tell Rampa. |
| 503 Service Unavailable | `FAUCET_UNAVAILABLE` | The faucet is not available right now. Try again later; tell Rampa if it persists. |
| 422 Unprocessable Entity | `AMOUNT_EXCEEDS_PROVIDER_LIMIT` | Above the per-payment cap. The body carries max\_amount. |
| 429 Too Many Requests | `TEST_QR_LIMIT_EXCEEDED` | More than 20 in an hour. retry\_after\_seconds says when. |
| 503 Service Unavailable | `TEST_QR_UNAVAILABLE` | The test environment could not make one right now. Try again shortly. |
| 422 Unprocessable Entity | `QR_REFUSED` | The QR cannot be paid: it is not a payment QR, or it has expired. Ask for a new one. |
| 404 Not Found | `RESOLUTION_NOT_FOUND` | No resolution with that id for your key. |
| 409 Conflict | `QUOTE_UNAVAILABLE` | We cannot quote that amount right now. Try a smaller amount, or later; tell Rampa if it persists. |
| 422 Unprocessable Entity | `CURRENCY_PAIR_NOT_AVAILABLE` | Only USDT → BOB is available. |
| 422 Unprocessable Entity | `SOURCE_AMOUNT_NOT_AVAILABLE` | Fixing source\_amount is not available yet. Send target\_amount. |
| 404 Not Found | `QUOTE_NOT_FOUND` | No quote with that id for your key. |
| 409 Conflict | `QUOTE_EXPIRED` | The quote expired. Nothing was attempted: get a new quote and show it to the end user. |
| 409 Conflict | `QUOTE_ALREADY_USED` | Another payment used this quote. Nothing was attempted: get a new quote. |
| 409 Conflict | `TRANSACTION_ID_REUSED` | This transaction\_id already belongs to a payment with a different body. Use a new transaction\_id for a new payment. |
| 422 Unprocessable Entity | `PAYOUT_TYPE_NOT_AVAILABLE` | type bank\_transfer is not available yet. Nothing was attempted. |
| 503 Service Unavailable | `OPERATION_UNCERTAIN` | We could not confirm the outcome. Retry with the same transaction\_id and the same body. |
| 404 Not Found | `QR_PAYOUT_NOT_FOUND` | No payment with that id for your key. |
| 409 Conflict | `WEBHOOK_LIMIT_REACHED` | You already have 10 endpoints. Delete one first. |
| 404 Not Found | `WEBHOOK_NOT_FOUND` | |
| 404 Not Found | `WEBHOOK_NOT_FOUND_OR_NOT_PAUSED` | |
| 503 Service Unavailable | `TENANT_NOT_PROVISIONED` | Your tenant setup is incomplete. Contact Rampa. |
| 503 Service Unavailable | `EBOB_UNAVAILABLE` | Temporary. Retry reads; resend writes unchanged (same `transaction_id` and body). |


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