Errors & denials
Every refusal has a reason and a fix. This page maps the messages you or your AI tool will actually see to what to do about them.
Signing in
| What you see | Why | Fix |
|---|---|---|
| 401 Unauthorized | No valid credential on the request, or your session/token expired. | Re-authenticate: OAuth apps refresh themselves or re-prompt; CLI users re-run the setup file. |
| api_key_retired | The tool sent the legacy X-API-Key header, which no longer signs in. | Re-run the setup file to switch to a session token, or connect over OAuth. |
| Session expired | Your session hit the admin sign-out timer. | Run the setup file again, or request no-logout from Session & login. |
| Code expired / invalid code | Email codes last 10 minutes and one use. | Request a fresh code and enter it promptly. |
| Account pending approval | You signed up but an admin hasn't approved you yet. | Wait for the approval email — nothing else is needed. |
| invalid_grant on refresh | Refresh tokens rotate — a used or revoked one is dead. | The app should re-run the sign-in flow; approve it again in the browser. |
Permission denials
| What you see | Why | Fix |
|---|---|---|
| Access denied for this client | The brand isn't in your granted scope. | Ask an admin via Help & support, naming the brand. |
| Access denied for this marketplace | The brand is yours but that marketplace isn't. | Same — an admin can widen your marketplace grant in seconds. |
| Write access required | You are view-only and called a WRITE tool. | Ask an admin for edit access, or stay read-only and export recommendations instead. |
| Rate limit exceeded | More than 60 tool calls in a minute from your account. | Wait a few seconds; batch questions instead of looping one call per row. |
Data answers that look like errors
| Symptom | What it usually means |
|---|---|
| A zero where you expected numbers | The filter may simply match nothing (a brand with no SB campaigns reports 0 SB spend), or the data feed for that client may not cover the dates asked. Cross-check with a broader question before concluding spend was zero. |
| Response truncated / too large | Some tools can return very large row dumps. Narrow by campaign, date range or client — filtered calls are dramatically smaller and faster. |
| A client name returns nothing | Client names must match the catalog exactly. Use the client list tool first and copy the name it returns. |
HTTP status codes
| Code | Meaning here |
|---|---|
| 200 | Success — including tool calls whose JSON body carries a denial message. |
| 302 | Redirect — normal for browser pages (sign-in, dashboard navigation). |
| 401 | Not signed in, or the credential expired / was revoked / is retired. |
| 403 | Signed in but not allowed — permission or approval missing. |
| 429 | Rate limited — slow down and retry. |
| 500 | Server-side fault. If it repeats, report it via Help & support with the time and the exact call. |