# Errors

Errors use the standard problem details format (RFC 9457), with `Content-Type: application/problem+json`:

```json
{
  "type": "https://developers.nepzio.com/errors/validation_failed",
  "title": "Unprocessable content",
  "status": 422,
  "detail": "Some fields are not valid; see errors.",
  "code": "validation_failed",
  "errors": [{ "field": "variants[0].price", "code": "invalid_money", "message": "variants[0].price must be whole rupees: a multiple of 100 paisa." }],
  "request_id": "req_3f9a1c0b7d2e4a6b8c9d0e1f"
}
```

- **Branch on `code`.** It is stable. `detail` and `message` are for people and may be reworded.
- **`errors`** lists problems with particular fields, by the name you sent (`variants[0].price`).
- **`request_id`**, also in the `X-Request-Id` header of every response, identifies the request. Quote it when you contact us.
- **New codes may appear.** Treat an unknown code by its HTTP status.

## Status codes

| Status | Meaning                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| 400    | The request couldn't be read: a bad parameter, invalid JSON, an unknown field |
| 401    | No key, or the key isn't valid                                                |
| 402    | The store's plan doesn't allow it (e.g. its product limit)                    |
| 403    | The key may not do this                                                       |
| 404    | Nothing with this id in your store, or no such endpoint                       |
| 405    | The endpoint doesn't take this HTTP method                                    |
| 409    | Not possible in the current state                                             |
| 415    | The body isn't JSON                                                           |
| 422    | The request was understood but some values aren't valid                       |
| 429    | Too many requests; wait for `Retry-After`                                     |
| 500    | Something went wrong on our side; retry later                                 |

## Codes

### authentication_required

No key was sent. Send `Authorization: Bearer <key>`.

### invalid_api_key

The key isn't valid: unknown, revoked, expired after a roll, or the account is suspended.

### browser_request_refused

The request came from a browser (it has an `Origin` header). Keys work only from a server.

### insufficient_scope

The key lacks the scope named in the message. Add it in **Settings → Developers**.

### forbidden

The key may not do this.

### not_found

Nothing with this id in your store (or a malformed id), or no endpoint at this address.

### method_not_allowed

The endpoint doesn't take this HTTP method. The `Allow` header lists those it does.

### unsupported_media_type

Send the body as JSON with `Content-Type: application/json`.

### invalid_request

The request couldn't be read, for example because the body isn't valid JSON.

### invalid_parameter

A query parameter, header or body field isn't valid, or the body has a field the endpoint doesn't take. `errors` names it.

### validation_failed

Some values aren't valid. `errors` names each field and says why.

### insufficient_stock

The change would take stock below zero.

### plan_limit_reached

The store's plan doesn't allow this, for example a new product beyond its product limit.

### order_not_cancellable

The order can't be cancelled: it has shipped, or is already finished.

### order_managed_elsewhere

The order came from a marketplace (Daraz, Amazon) and is managed there.

### idempotency_key_in_use

A request with the same `Idempotency-Key` is still running. Retry shortly.

### idempotency_key_reused

This `Idempotency-Key` was used for a different request. Use a new key per distinct request.

### rate_limited

Too many requests. Wait for the seconds in `Retry-After`. See [Rate limits](/rate-limits).

### internal_error

Something went wrong on our side. Retry later; if it keeps happening, contact us with the `request_id`.