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

# Errors and integration notes

> Vanryx Merchant API error responses, rate limits, and data-format notes for integrators.

## Error responses

| HTTP status | Endpoint | Cause |
| - | - | - |
| `401` | All | `{"message":"Missing merchant API Key"}`: the `Merchant-API-Key` header is absent. |
| `401` | All | `{"message":"Invalid or inactive API Key"}`: the key is not valid and active. |
| `409` | [Create Invoice](https://docs.vanryx.com/api-reference/create-invoice.md) | `IDEMPOTENCY_KEY_REUSED`: an `Idempotency-Key` was reused with different request data. |
| `422` | All | Field validation failed. |
| `422` | [Create Invoice](https://docs.vanryx.com/api-reference/create-invoice.md) | Unsupported fields (`allowed_assets`, `to_currency`, `network`) or an unavailable capability (`sandbox`, `mixed_payment`, `auto_withdrawal`) set to `true`. |
| `422` | [Create Static Address](https://docs.vanryx.com/api-reference/create-static-address.md) | `{"message":"Wrong currency code."}` for an unsupported currency and network pair, or a service message when the Merchant account, active asset, or address setup is unavailable. |
| `422` | [Get Rate](https://docs.vanryx.com/api-reference/get-rate.md) | `{"message":"Wrong currency code."}` for an unrecognized `from_currency`, or a `Rate … not found.` message when no matching stored pair exists. |
| `429` | [Create Invoice](https://docs.vanryx.com/api-reference/create-invoice.md) | The route limit of 10 requests per minute was exceeded. |
| `503` | [Create Invoice](https://docs.vanryx.com/api-reference/create-invoice.md) | `INVOICE_LINK_UNAVAILABLE`, `INVOICE_ID_UNAVAILABLE`, or `INVOICE_CREATION_UNAVAILABLE`. |

Service error messages vary. This is not an exhaustive list of messages.

## Validation errors

Validation errors return a `message` and an `errors` object with messages for each field. This example shows the shape only. Exact messages may differ:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}
```

## Rate limits

* [Create Invoice](https://docs.vanryx.com/api-reference/create-invoice.md) is limited to 10 requests per minute.
* Other routes may also return HTTP `429`. Their limits are not documented.
* No rate-limit response headers are documented. Back off before you retry after a `429`.

## Integration notes

* **Request format:** the examples send JSON bodies with `Content-Type: application/json`.
* **Invoice amounts:** send `amount` as a JSON string, for example `"49.95"`, to preserve decimal precision.
* **Rate values:** `data.rate` from [Get Rate](https://docs.vanryx.com/api-reference/get-rate.md) is a JSON number. It is a stored reference rate, not an executable or guaranteed price.
* **Webhook amounts:** `transaction.sent_amount`, `transaction.service_fee`, and `transaction.received_amount` are JSON numbers. Invoice decimal fields such as `amount_due` and `amount_paid` are strings.
* **Webhook timestamps:** Unix seconds, or JSON `null` when not recorded.
* **Fulfillment:** fulfill invoices only when the callback reports `fulfilled: true`. See [Webhooks](https://docs.vanryx.com/webhooks.md).
* **XRP:** always use the returned `destination_tag` when it is not `null`.
* **API keys:** keep them in server-side secret storage. See [API keys and authentication](https://docs.vanryx.com/authentication.md).


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