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

# Errors

> Every error has the same shape and a stable code.

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This needs the orders:write scope.",
    "request_id": "8a3b0f4e-2c6d-4f1a-9b7e-1d2c3b4a5f60"
  }
}
```

Build your logic on `code`, which never changes. `message` is for people and may be reworded. Include `request_id` when you contact BrandGate support.

| Status | Code | What to do |
| - | - | - |
| 400 | `invalid_request` | Fix the request; the message names the field. |
| 401 | `unauthorized` | The key or token is missing, unknown, expired or revoked. Refresh an OAuth token; otherwise ask for a new key. |
| 403 | `insufficient_scope` | The key or connection lacks the scope named in the message. |
| 403 | `organization_unavailable` | The company's BrandGate account is not reachable through the API right now. |
| 404 | `not_found` | The object does not exist or belongs to another company. |
| 409 | `already_acknowledged` | The order was acknowledged with a different ERP number. |
| 409 | `inventory_managed_by_erp` | The company already imports stock from an ERP connected in BrandGate. Only one system can own stock; ask the company to turn that import off. |
| 409 | `limit_reached` | A per-company limit, such as the number of webhook endpoints. |
| 413 | `payload_too_large` | Request bodies are limited to 256 KB. |
| 429 | `rate_limited` | Wait for `Retry-After` seconds. See [rate limits](/rate-limits). |
| 502, 503 | `unavailable` | A temporary problem. Retry with backoff. |
| 500 | `internal_error` | Retry with backoff and contact support if it persists. |

Retrying `GET` requests is always safe. `POST /v1/orders/{id}/acknowledge` with the same number and `POST /v1/inventory` with the same levels are idempotent, so they are safe to retry too.

## OAuth errors

The `/oauth/*` endpoints follow RFC 6749 instead: `{"error": "invalid_grant", "error_description": "…"}`.


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