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

# Errors

> The error format, the fields to branch on, and every error the API returns

Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with the content type `application/problem+json`:

```json theme={null}
{
  "type": "https://docs.alura.io/errors/fetch_limit_reached",
  "title": "Fetch limit reached",
  "status": 429,
  "code": "fetch_limit_reached",
  "detail": "This workspace has reached a limit on fetching items Alura has not seen yet.",
  "suggestion": "Wait for Retry-After before asking for items Alura has not seen.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}
```

| Field | Description |
| - | - |
| `type` | A link to the error's page on this site. |
| `title` | A short summary. The wording can change. |
| `status` | The HTTP status code. |
| `code` | The stable error code. Branch on this. |
| `detail` | What went wrong with this request. The wording can change. |
| `suggestion` | What to change, or what to do next. |
| `retryable` | `true` when the same request can succeed later. |
| `request_id` | The same ID as the `Request-Id` header. Include it when you contact support. |

Branch on `code`, never on `title` or `detail`. When `retryable` is `true`, wait for the `Retry-After` header if there is one, and back off if there isn't. Some errors add fields, such as `upgrade_url` on `402 credits_exhausted` or `valid_fields` on a bad `fields` path. Each error's page lists them.

Errors never cost API credits. MCP tools return the same errors as a tool result with `isError: true`, carrying `code`, `suggestion` and `retryable`.

[Handling errors](/guides/handling-errors) has a retry helper in curl, TypeScript and Python.

## All errors

| Code | Status | Retry | Meaning | What to do |
| - | - | - | - | - |
| [`invalid_request`](/errors/invalid_request) | 400 | No | Invalid request | Fix the request as the detail says, then send it again. |
| [`unknown_parameter`](/errors/unknown_parameter) | 400 | No | Unknown parameter | Remove the parameter or use one this operation accepts. |
| [`invalid_cursor`](/errors/invalid_cursor) | 400 | No | Invalid cursor | Start again from the first page without a cursor; a cursor only works with the query that produced it. |
| [`cursor_window_exceeded`](/errors/cursor_window_exceeded) | 400 | No | Cursor window exceeded | Narrow the query; paging stops after 10,000 results. |
| [`id_type_mismatch`](/errors/id_type_mismatch) | 400 | No | Wrong ID type | Pass an ID of the type this operation takes. |
| [`invalid_keyword`](/errors/invalid_keyword) | 400 | No | Invalid keyword | Send keywords of 1-100 characters. |
| [`unauthorized`](/errors/unauthorized) | 401 | No | Unauthorized | Send a valid API key as `Authorization: Bearer alura_sk_...`. |
| [`credits_exhausted`](/errors/credits_exhausted) | 402 | No | API credits exhausted | Upgrade the plan or wait for the monthly reset. |
| [`plan_required`](/errors/plan_required) | 403 | No | Plan required | Upgrade the workspace plan to use this operation. |
| [`insufficient_scope`](/errors/insufficient_scope) | 403 | No | Insufficient scope | Use a key or grant that carries the scope this operation needs. |
| [`workspace_required`](/errors/workspace_required) | 403 | No | Workspace required | Choose a workspace with switch\_workspace, then retry. |
| [`workspace_locked`](/errors/workspace_locked) | 403 | No | Workspace locked | API keys are bound to one workspace; create a key in the other workspace. |
| [`browser_refused`](/errors/browser_refused) | 403 | No | API keys are refused from browsers | Call the API from a server or script, and keep the key out of web pages. |
| [`role_required`](/errors/role_required) | 403 | No | Owner or admin required | Ask a workspace owner or admin to manage API keys. |
| [`impersonation_refused`](/errors/impersonation_refused) | 403 | No | Not while viewing as a user | Keys cannot be created or rotated during an impersonation session; the user must do it. |
| [`recent_sign_in_required`](/errors/recent_sign_in_required) | 403 | No | Recent sign-in required | Sign in again, then retry within 10 minutes. |
| [`not_found`](/errors/not_found) | 404 | No | Not found | Check the ID, or search for it first. |
| [`not_found_on_etsy`](/errors/not_found_on_etsy) | 404 | No | Not found on Etsy | Etsy has no such item; check the ID or name. |
| [`shop_opted_out`](/errors/shop_opted_out) | 404 | No | Shop opted out | This shop asked Alura not to track it; its data is not available. |
| [`method_not_allowed`](/errors/method_not_allowed) | 405 | No | Method not allowed | Use one of the methods in the Allow header. |
| [`conflict`](/errors/conflict) | 409 | No | Conflict | Reload the resource and retry with its current state. |
| [`key_limit_reached`](/errors/key_limit_reached) | 409 | No | API key limit reached | Revoke a key you no longer use; a workspace has at most 25 active keys. |
| [`idempotency_processing`](/errors/idempotency_processing) | 409 | Yes | Request still processing | Retry the same request after a moment. |
| [`unprocessable`](/errors/unprocessable) | 422 | No | Unprocessable | Fix the request as the detail says. |
| [`rate_limited`](/errors/rate_limited) | 429 | Yes | Rate limited | Wait for Retry-After, then retry. |
| [`throttled`](/errors/throttled) | 429 | Yes | Throttled | Wait for Retry-After, then retry at a lower rate. |
| [`daily_credit_cap_exceeded`](/errors/daily_credit_cap_exceeded) | 429 | Yes | Daily API credit ceiling reached | Retry after the next UTC midnight. |
| [`credits_reserved`](/errors/credits_reserved) | 429 | Yes | API credits held by calls in flight | Retry in a few seconds. |
| [`fetch_limit_reached`](/errors/fetch_limit_reached) | 429 | Yes | Fetch limit reached | Wait for Retry-After before asking for items Alura has not seen. |
| [`internal_error`](/errors/internal_error) | 500 | Yes | Internal error | Retry; if it keeps failing, report the request\_id. |
| [`upstream_unavailable`](/errors/upstream_unavailable) | 502 | Yes | Upstream unavailable | Retry shortly. |
| [`credits_unavailable`](/errors/credits_unavailable) | 503 | Yes | API credits unavailable | Retry shortly. |
| [`service_unavailable`](/errors/service_unavailable) | 503 | Yes | Service unavailable | Retry shortly; if it keeps failing, report the request\_id. |
| [`fetch_unavailable`](/errors/fetch_unavailable) | 503 | Yes | Fetching unavailable | Alura cannot fetch new items from Etsy right now; retry later. |
| [`upstream_timeout`](/errors/upstream_timeout) | 504 | Yes | Timed out | Retry shortly; if it keeps timing out, narrow the request or report the request\_id. |


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