---
id: errors
title: "Errors"
sidebar_label: Errors
hide_title: true
description: "Management API - HTTP status codes and what to do about each one"
---

import Ingress from '../../src/components/ingress/ingress.react';

<Ingress title="Errors">
    The Management API draws its responses from one small set of HTTP status codes, and each one
    means the same thing wherever you meet it. This page defines them and says what to do next, so
    you can handle them in one place. Which codes a given endpoint can return is listed at the
    bottom.
</Ingress>

## Status codes

| Code  | What it means                                                                  | What to do                                                                                                             |
| ----- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `200` | The request succeeded and the body carries the result.                         | Nothing.                                                                                                               |
| `201` | A reauthorization to a higher amount started and needs a credit check.         | Poll the URL in the `Location` header. See [Asynchronous operations](/docs/manage/concepts/asynchronous-operations).    |
| `202` | Walley accepted the write and will apply it shortly.                           | Do not read the order back immediately. See [Asynchronous operations](/docs/manage/concepts/asynchronous-operations).   |
| `401` | The token is missing, expired, or invalid.                                     | Request a new access token. See [Authentication](/docs/manage/getting-started/authentication).                          |
| `403` | Your credentials do not cover this store, or the order has not finished syncing. | Check the store your API key covers. If the order was just created, retry after at least 3 seconds.                    |
| `404` | No order matches that id, the order has not finished syncing, or you passed a `correlationId` whose action has not been applied yet. | Check the id. Otherwise retry after at least 3 seconds. See [Get order](/docs/manage/orders/get) for the `correlationId` case. |
| `409` | A request with the same idempotency key is already running.                     | Wait, then read the order back. Reuse the same key if you retry. See [Idempotency](/docs/manage/idempotency).           |
| `422` | The request conflicts with the state of the order or breaks a validation rule.  | Do not retry. Read the error code in the response and fix the request.                                                 |

:::note A 403 or 404 right after a purchase is usually the sync delay
Walley applies order changes asynchronously, so a brand new order can answer `403` or `404` for a
few seconds before it is readable. Retry once after 3 seconds before treating it as a real
failure. See [Asynchronous operations](/docs/manage/concepts/asynchronous-operations).
:::

## Handling 422

A `422` carries an error code that names the exact rule you hit. The codes are specific to the
endpoint, so look them up where you called:

- [Capture order error codes](/docs/manage/orders/capture#error-codes)
- [Refund order error codes](/docs/manage/orders/refund#error-codes)
- [Reauthorize order error codes](/docs/manage/orders/reauthorize#error-codes)

Most of them fall into three groups.

**The amount does not add up.** When you send `items`, `amount` has to equal their total.
Amounts take at most 2 decimals.

**The order is in the wrong state.** You cannot capture a captured order, refund a fully refunded
one, or touch an order that is closed or expired. Check the status first with
[Order lifecycle](/docs/manage/concepts/order-lifecycle).

**An item could not be matched.** Partial captures and refunds match the items you send against
the items on the order. Send `unitPrice` and `quantity` at minimum, and the more fields you send,
the more likely the match is unique.

## Which endpoints return what

| Endpoint                                             | Success | Also possible                    |
| ---------------------------------------------------- | ------- | -------------------------------- |
| [Get order](/docs/manage/orders/get)                 | `200`   | `401`, `403`, `404`              |
| [Capture order](/docs/manage/orders/capture)         | `202`   | `401`, `403`, `404`, `409`, `422` |
| [Refund order](/docs/manage/orders/refund)           | `202`   | `401`, `403`, `404`, `409`, `422` |
| [Cancel order](/docs/manage/orders/cancel)           | `202`   | `401`, `403`, `404`, `409`       |
| [Reauthorize order](/docs/manage/orders/reauthorize) | `202`   | `201`, `401`, `403`, `404`, `409`, `422` |

## Next steps

- [Asynchronous operations](/docs/manage/concepts/asynchronous-operations) covers retries and idempotency in full
- [Order lifecycle](/docs/manage/concepts/order-lifecycle) covers which actions a status allows