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

# Errors and Request IDs

> Handle errors from the storekit API: the error object, every error type and code, validation and server errors, and the request ID to quote to support.

The API uses HTTP status codes to say whether a request worked: `2xx` for success, `4xx` for a request that cannot be carried out as sent, and `5xx` for a failure on our side. Every `4xx` and `5xx` response under `/v1` has the same JSON body, including the `404` for a path that does not exist.

## The Error Object

```json theme={null}
{
    "error": {
        "type": "invalid_request_error",
        "code": "parameter_invalid",
        "message": "Invalid value for parameter: limit.",
        "param": "limit",
        "doc_url": "https://docs.storekit.com/developers/api/errors#parameter_invalid",
        "request_id": "req_019a8f3b2c4d7e6f8a9b0c1d2e3f4a5b"
    }
}
```

| Field | Type | Meaning |
| - | - | - |
| `type` | string | The category of the error. It decides how to handle it. See [Types](#types). |
| `code` | string | What went wrong. See [Codes](#codes). |
| `message` | string | A description for you, the developer. Do not show it to your users and do not match on its text: it can be reworded at any time. |
| `param` | string or `null` | The request parameter the error is about, when there is one. |
| `doc_url` | string | A link to the code's entry on this page. |
| `request_id` | string | The ID of the request. See [Request IDs](#request-ids). |

All six fields are always present. A field with no value is `null`, never left out.

### Handle Errors by Type, then by Code

* Branch on `type` first. There are few types and each maps to one way of handling the error.
* Branch on `code` where you need more detail.
* **New codes are added over time.** When you meet a code you do not know, handle it by its `type`. A code that has shipped is never renamed and never reused for another meaning.
* Never branch on `message`.

## Types

| `type` | Status | What it means | What to do |
| - | - | - | - |
| `authentication_error` | `401` | The request has no valid credentials. | Fix the key. Do not retry with the same key. See [Authentication](https://storekit.com/docs/developers/api/authentication). |
| `permission_error` | `403` | The credentials are valid but are not allowed to make this request. | Use a key that is allowed to. Do not retry. |
| `invalid_request_error` | `400`, `404`, `409`, `422` | The request cannot be carried out as sent. | Fix the request. Do not retry it unchanged. |
| `idempotency_error` | `409` | An idempotency key was used in a way that is not allowed. | Send the original request again, or use a new key for a new request. |
| `rate_limit_error` | `429` | Too many requests. | Wait, then retry. Follow the `Retry-After` header when the response has one. |
| `api_error` | `500` and above | Something failed on our side or in a service the request depends on. | See [Server errors](#server-errors). |

## Codes

Each heading below is a value of `code`.

### credentials\_missing

`401` `authentication_error`. No credentials were provided. A request without an API key normally gets the more specific [`api_key_missing`](#api_key_missing).

### credentials\_invalid

`401` `authentication_error`. The credentials provided are not valid. A refused API key normally gets the more specific [`api_key_invalid`](#api_key_invalid).

### api\_key\_missing

`401` `authentication_error`. The request has no API key. Send one in the `Authorization` header: see [Authentication](https://storekit.com/docs/developers/api/authentication#send-your-key).

### api\_key\_invalid

`401` `authentication_error`. The API key was not accepted. This is the answer for a mistyped key, a key that was never issued, a revoked key and an expired key alike. See [When a key is refused](https://storekit.com/docs/developers/api/authentication#when-a-key-is-refused).

### scope\_insufficient

`403` `permission_error`. The key is valid but does not have the scope this request needs. Use a key that has it.

### permission\_denied

`403` `permission_error`. The key is valid but is not allowed to make this request.

### parameter\_missing

`400` `invalid_request_error`. A required parameter was not sent. `param` names it.

### parameter\_invalid

`400` `invalid_request_error`. A parameter has a value that is not accepted: the wrong type, out of range, or not one of the allowed values. `param` names it.

### parameter\_unknown

`400` `invalid_request_error`. The request has a parameter the endpoint does not know. `param` names it. An unknown parameter is refused, not ignored.

### cursor\_invalid

`400` `invalid_request_error`. A cursor in `starting_after` or `ending_before` was not issued by this list for this request: it was changed, or it came from another list, another account, another set of filters or another sort. `param` names the parameter that held it. Start the list again without a cursor: the same cursor will not work on a retry. See [Pagination](https://storekit.com/docs/developers/api/pagination#cursors).

### request\_invalid

`400` `invalid_request_error`. The request is invalid in a way that is not about one parameter.

### resource\_not\_found

`404` `invalid_request_error`. The path is a real endpoint, but the resource it names was not found.

### route\_not\_found

`404` `invalid_request_error`. No endpoint matches this method and path. Check the path and the HTTP method against the reference.

### resource\_conflict

`409` `invalid_request_error`. The request conflicts with the current state of the resource. Fetch the resource, then decide whether the request still applies.

### request\_unprocessable

`422` `invalid_request_error`. The request is well formed but could not be carried out.

### idempotency\_key\_conflict

`409` `idempotency_error`. The idempotency key was already used with a different request. Use a new key for a new request.

### idempotency\_key\_in\_use

`409` `idempotency_error`. An earlier request with this idempotency key is still being processed. Wait, then send the same request again with the same key, following the `Retry-After` header when the response has one. Do not switch to a new key: that could carry out the write twice.

### rate\_limit\_exceeded

`429` `rate_limit_error`. Too many requests. Slow down and retry later, following the `Retry-After` header when the response has one.

### upstream\_unavailable

`502` `api_error`. A service this request depends on is unavailable. **A write may still have completed.**

### request\_timeout

`504` `api_error`. The request timed out. **A write may still have completed.**

### service\_unavailable

`503` `api_error`. The service is temporarily unavailable. Try again later.

### internal\_error

`500` `api_error`. Something failed on our side. **A write may still have completed.** If it keeps happening, contact support with the request ID.

## Validation Errors

A request with a missing, invalid or unknown parameter is answered with `400` and one of `parameter_missing`, `parameter_invalid` or `parameter_unknown`.

* `param` names the parameter. A nested field is a dot path, such as `customer.email`. An item of an array is named by its position, such as `items.0.quantity`.
* **Only the first problem is reported.** A request with several invalid parameters gets one error. Fix it and send the request again to see the next.
* A `param` longer than 100 characters is cut to 100 and ends in `...`.

## Server Errors

A `5xx` response means the failure is not caused by your request. The body has the same shape, with the type `api_error`, and never contains internal details.

* **Reading** (`GET`): retry, waiting longer between attempts each time, such as 1, 2, 4 and 8 seconds with some random variation, and stop after a few attempts.
* **Writing**: do not assume the write failed. After `internal_error`, `request_timeout` or `upstream_unavailable` the change may have been made. Fetch the resource to see its current state before sending the write again.

If a `5xx` persists, contact support with the request ID.

## Request IDs

Every response under `/v1` carries a request ID, whether the request succeeded or failed:

* in the `Request-Id` response header, on every response;
* in `error.request_id`, on an error.

```
Request-Id: req_019a8f3b2c4d7e6f8a9b0c1d2e3f4a5b
```

A request ID is `req_` followed by 32 hexadecimal characters. The two places always hold the same value for one response.

* **Log the `Request-Id` of every response**, successes included. It is the quickest way for support to find what happened to one request.
* **Quote it when you contact support.** Never send your API key.
* The ID is created by the API. A request ID that you send, for example in an `X-Request-Id` header, is not used. To follow a request through your own systems, log your own identifier next to the `Request-Id` you receive.
* Each attempt has its own ID: a retried request gets a new one.


## Related topics

- [Errors](https://storekit.com/docs/developers/mcp/errors.md)
- [POS Troubleshooting](https://storekit.com/docs/guides/integrations/pos/advanced/troubleshooting.md)
- [Permissions & Privacy](https://storekit.com/docs/guides/ai/permissions-and-privacy.md)
- [Check Pay at Table payment status from POS or dashboard](https://storekit.com/docs/guides/pay-at-table/checking-payments.md)
- [Merchant MCP Overview](https://storekit.com/docs/developers/mcp/overview.md)


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