> ## 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.

# Troubleshooting

> The most common problems and how to fix them.

> **I get 401 unauthorized**
>
> The key or token is missing, mistyped, expired or revoked. Check that the header is `Authorization: Bearer bg_live_…`. For OAuth, refresh the access token (it lasts 1 hour). If the key was revoked in **Settings → Developers**, create a new one.

> **I get 403 insufficient\_scope**
>
> The key can only do what its scopes allow. The error names the missing scope. Create a new key with that scope, or ask the company to approve it again. A write scope never includes the matching read scope.

> **I get 404 for something that should exist**
>
> Objects from another company look like they do not exist. Check that the key belongs to the right company. Draft orders are never returned by the API.

> **Stock updates answer 409 inventory\_managed\_by\_erp**
>
> An ERP connected inside BrandGate already controls stock. Only one system can own it. The company can turn that import off in **Settings → ERP**.

> **I get 429 rate\_limited**
>
> Wait for `Retry-After` seconds. Use [webhooks](/webhooks) and `updated_since` instead of polling. See [rate limits](/rate-limits).

> **Webhooks do not arrive**
>
> Check that the endpoint is `https://` on port 443 with a public address, that it answers `200` quickly, and that it subscribed to the event. Verify the signature with the raw request body, not re-serialised JSON. Run a [catch-up sweep](/guides/erp-sync#2-catch-up) so nothing depends on a single delivery.

> **The API answers 503 or 502**
>
> That is a temporary problem. Retry with backoff. The public API can also be switched off for a company or for the whole platform; if it stays unavailable, contact us.

> **My AI assistant cannot connect**
>
> Check the URL `https://api.brandgate.dev/mcp`. Signing in with OAuth needs a company admin to approve the access. Clients that cannot do OAuth can use an [API key](/authentication) as a header. See [MCP server](/mcp).

## Still stuck?

Write to us through [brandgate.dev/contact](https://www.brandgate.dev/contact) and include the `request_id` from the error response. It lets us find your exact request.


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