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

# Errors and Retries

> The error shape, what each status means, and when it's safe to send a request again

Every error has the same shape, apart from `POST /oauth2/token`, whose errors follow OAuth 2.0.

```json theme={null}
{
  "error": {
    "code": "REFUND_AMOUNT_EXCEEDED",
    "message": "The refund amount is more than the refundable amount.",
    "details": [{ "field": "amount.value", "message": "Must be 4500 or less" }],
    "retryable": false,
    "request_id": "req_1"
  }
}
```

| Field | Meaning |
| - | - |
| `code` | What went wrong. **Branch on this**, not on `message`. Each endpoint lists its codes in the reference, and new codes can appear, so handle any you don't recognise. |
| `message` | For people. It can change. |
| `details` | Structured information, documented for each code: the `field` a validation failure is about, the agreement a consent names, or the record a refusal is about. `[]` when there's nothing to add. |
| `retryable` | `true` when the same request, sent again unchanged after a wait, can succeed with nothing else changing. `false` when something has to change first: the request, or the state or set-up it depends on. |
| `request_id` | Quote it to support. Every response, success or failure, also carries it in the `X-Request-Id` header. |

## Status Codes

| Status | Meaning | What to do |
| - | - | - |
| 400 | The request is wrong whoever sends it, and whichever merchant or record it names: it's malformed, it names something that doesn't exist or that you can't reach, or it holds a value or a combination Quidkey doesn't support anywhere | Fix the request. `details` names the field. |
| 401 | Not authenticated | Get a new token. |
| 403 | No permission for this endpoint | Your credential can't do this. |
| 404 | Doesn't exist, or outside your scope | A 404 never confirms that something exists elsewhere. |
| 405 | Wrong method on a known path | Fix the request. |
| 406 | The endpoint doesn't offer the format in `Accept` | Ask for JSON. |
| 409 | The request is sound, but the current state prevents it | The same request can succeed once the state changes. |
| 422 | The request is sound, but a rule refuses it because of the merchant or record it targets: its set-up, its limits, its route or its type | Change the request, or the set-up of what it targets. Sending the same request again won't help. |
| 429 | Rate limited | Wait for `Retry-After`, then send it again. |
| 500 | Our fault | Contact support with the `request_id`. |
| 502, 503 | A dependency failed, or we're busy | If `retryable`, wait for `Retry-After`, then send it again. See below for `OUTCOME_UNKNOWN`. |

Any endpoint that takes a token can answer `VALIDATION_FAILED`, `UNAUTHENTICATED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR` and `SERVICE_UNAVAILABLE`, and any that answers with a body can answer `NOT_ACCEPTABLE`. Handle a 429 from any endpoint: wait for `Retry-After`, then send the request again.

## Unknown Outcomes

A write can lose its answer: a timeout, a dropped connection, a dependency that stopped responding. Two 503 codes tell you what that means for your next step.

| Code | Meaning | What to do |
| - | - | - |
| `SERVICE_UNAVAILABLE` | Nothing was done, or doing it again is harmless. `retryable: true`, with `Retry-After`. | Send the same request again. |
| `OUTCOME_UNKNOWN` | The write may have taken effect without saying so. `retryable: false`, with no `Retry-After`. | Do what the endpoint's row below says. For most, **read the resource first**, then decide, because sending it again could do it twice. |

Only a write with no `Idempotency-Key` answers `OUTCOME_UNKNOWN`. Each endpoint that can lists it in the reference, and is in this table:

| Endpoint | After `OUTCOME_UNKNOWN` |
| - | - |
| `POST /merchants/{id}/legal-entities` | List the merchant's legal entities. A merchant has one, so a repeat answers `LEGAL_ENTITY_ALREADY_EXISTS`, naming it in `details`. |
| `DELETE /parties/{id}` | Read the party. A 404 means it's gone. |
| `PATCH /webhook-endpoints/{id}` | Read the endpoint. If the patch turned signing on, its secret may have been issued: rotate it to get one you hold. |
| `POST /webhook-endpoints/{id}:rotateSecret` | The secret may have been replaced. Rotate again to get one you hold. |
| `POST /transactions/{id}:executeRefund` | It answers this when its answer was lost, when the request ran out of time while the refund was still moving, and when the refund's movement is unknown until Quidkey checks with the provider. The refund goes on either way. Send `:executeRefund` again, which is safe, or read the refund, to see where it stands. |
| `POST /merchants/{id}/capabilities/{capability_id}:request` | It answers this only when a provider may hold something for the merchant that Quidkey hasn't recorded. Contact Quidkey: until Quidkey has checked, a repeat answers `OUTCOME_UNKNOWN` again. A lost answer is `SERVICE_UNAVAILABLE`: send it again. |

With an `Idempotency-Key`, a lost answer is always `SERVICE_UNAVAILABLE`, because the same key and body recover the first attempt's outcome. See [Idempotency](https://docs.quidkey.com/api-v1/standards/idempotency.md).

## Safe to Repeat

Some writes take no `Idempotency-Key` because repeating them does no more than the first call did. Their reference says **Safe to repeat**, and after `SERVICE_UNAVAILABLE` you send the same request again. `:executeRefund` and a capability's `:request` can also answer `OUTCOME_UNKNOWN`, and [Unknown Outcomes](#unknown-outcomes) says what to do for each.

| Endpoint | Why a repeat is harmless |
| - | - |
| `POST /transactions/{id}:issueCheckout` | It answers the same live checkout, and never rotates a token a customer is using. |
| `POST /transactions/{id}:executeRefund` | A refund already moving answers 200 with the refund. |
| `POST /parties/{id}:verifyIdentity` | It answers the check already in flight, with its link. |
| `POST /merchants/{id}/agreement-acceptances` | A version already on file answers 200 with the acceptance. |
| `POST /merchants/{id}/capabilities/{capability_id}:request` | One already requested answers 200 with the capability. |
| `POST /bank-accounts/{id}:deactivate` | An account already `inactive` answers 200 with no change. |
| `PATCH` on a merchant, a legal entity or a party | It sets the same fields again. |

`GET` is always safe to repeat. A repeated `DELETE` answers 404, which you can treat as success.


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