> For the complete documentation index, see [llms.txt](https://docs.qiro.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qiro.fi/developer-section/qiro-instant-settlement/errors-and-idempotency.md).

# Errors and idempotency

Qiro returns stable error codes in a standard envelope. Use the code and `retryable` flag to decide what to do next.

## What to do next

| Situation                         | Examples                                                               | Partner action                                                                                                                   |
| --------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Authentication failed             | `UNAUTHORIZED`, missing scope                                          | Refresh credentials or request the required scope.                                                                               |
| Resource is not visible           | `404`                                                                  | Check the ID and authenticated partner; cross-partner resources are intentionally indistinguishable.                             |
| Duplicate safety conflict         | `IDEMPOTENCY_CONFLICT`                                                 | Stop and inspect the original operation. Do not retry with changed payload under the same key.                                   |
| Resource not in the right state   | `DRAWDOWN_NOT_READY`, `REPAYMENT_NOT_READY`, `DRAWDOWN_NOT_FUNDED`     | Read the status endpoint and continue from the current state.                                                                    |
| Business or facility rejection    | `INSUFFICIENT_AVAILABLE_LIMIT`, `INVALID_TENOR`, `FACILITY_NOT_ACTIVE` | Correct the request or resolve the facility condition before retrying.                                                           |
| Wallet or chain mismatch          | `WALLET_MISMATCH`, `CHAIN_MISMATCH`                                    | Connect the active designated wallet on the facility chain.                                                                      |
| Temporary infrastructure failure  | `RLOC_SERVICE_UNAVAILABLE`                                             | Retry safely with the same idempotency key where the endpoint requires one.                                                      |
| Repayment quote expired           | `REPAYMENT_QUOTE_EXPIRED`                                              | Create a fresh repayment so Qiro can calculate a new fixed maximum.                                                              |
| Receipt uncertain after broadcast | `RECEIPT_WAIT_FAILED`, reconciliation timeout                          | Do not submit another financial transaction automatically. Query the status endpoint using the resource ID and transaction hash. |

## Idempotency keys

Money-sensitive creation endpoints require `X-Idempotency-Key`.

The same key and same request return the original resource. The same key with a different request returns `IDEMPOTENCY_CONFLICT`.

Idempotency keys prevent accidental duplicate resource creation. They are not credentials and are separate from correlation IDs.

SDK methods generate and reuse idempotency keys internally where they own the workflow. Direct REST integrations should generate a new UUID per logical operation and persist it with the partner’s local operation record.

## Correlation IDs

Correlation IDs are for tracing. They can appear in API responses and webhooks. Reusing or changing a correlation ID does not bypass idempotency, authorization, wallet checks, or contract validation.

## Safe retry rules

* Retry read requests freely.
* Retry creation requests with the same idempotency key after transport failure.
* Retry preparation requests when no transaction was signed or when instructed by the current status.
* After a wallet returns a transaction hash, do not blindly resubmit. Read the resource status and reconcile the known transaction hash.
