Errors

Errors use RFC 9457 problem details, with the content type application/problem+json:

{
  "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"
}

code is stable: branch on it, not on title or detail, whose wording can change.
retryable says whether the same request can succeed later. When it is true, wait for the Retry-After header if there is one, and back off if there isn’t.
suggestion says what to change.
request_id is also in the Request-Id header of every response, errors or not. Include it when you contact support.
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 has a retry helper in curl, TypeScript and Python.

All errors

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

Get started

Concepts

Guides

Research features

Methodology

Resources

Legal

All errors

​All errors

All errors