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.
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. |
202 | Walley accepted the write and will apply it shortly. | Do not read the order back immediately. See Asynchronous operations. |
401 | The token is missing, expired, or invalid. | Request a new access token. See 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 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. |
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. |
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.
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:
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.
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 | 200 | 401, 403, 404 |
| Capture order | 202 | 401, 403, 404, 409, 422 |
| Refund order | 202 | 401, 403, 404, 409, 422 |
| Cancel order | 202 | 401, 403, 404, 409 |
| Reauthorize order | 202 | 201, 401, 403, 404, 409, 422 |
Next steps
- Asynchronous operations covers retries and idempotency in full
- Order lifecycle covers which actions a status allows