Error Handling

Every failure is a JSON envelope with a stable code, a more specific reason, and a request_id. Branch on code and reason; never on message, whose wording may change. This page is generated from the API's OpenAPI specification and its reason registry.

The envelope

Every non-2xx response has this shape, and success is always false.

1{2  "success": false,3  "error": {4    "code": "FORBIDDEN",5    "reason": "PLAN_REQUIRED",6    "message": "This endpoint requires 'studio' tier or above. Your tier: 'builder'",7    "details": {8      "requiredTier": "studio",9      "currentTier": "builder"10    }11  }12}

codestringrequired
Machine-readable error code, e.g. NOT_FOUND, RATE_LIMITED, SUBSCRIPTION_REQUIRED. Branch on this, never on message.
reasonenumrequired
Which situation, within code. Stable and machine-readable: branch on this, never on message. Each error response lists the reasons it can carry, and the error reference says what to do about each.
messagestringrequired
Human-readable account of what went wrong. The wording may change; treat it as text for a log or a person, not as a value to match on.
detailsobjectoptional
Structured context for the reason: the invalid fields for INVALID_PARAMETER, requiredTier for PLAN_REQUIRED.
request_idstringoptional
Quote this to support: it finds the request in our logs.

Status codes

The HTTP statuses an error can carry, the situations each one covers, and how many endpoints declare it.

Status	Description	Reasons	Endpoints
400	Validation error	`INVALID_PARAMETER` `INVALID_JSON` `INVALID_REQUEST`	132
401	Missing or invalid API key	`AUTH_REQUIRED` `KEY_MISSING` `KEY_INVALID` `KEY_DISABLED` `KEY_EXPIRED` `SIGN_IN_REQUIRED` `SESSION_EXPIRED` `ACCOUNT_NOT_FOUND` `LINK_EXPIRED` `PROXY_CREDENTIAL_INVALID`	118
403	The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work.	`PLAN_REQUIRED` `ACCOUNT_SUSPENDED` `KEY_NOT_LINKED_TO_ACCOUNT` `KEY_NOT_LINKED_TO_SHOP` `SHOP_UNDER_REVIEW` `NOT_OWNER` `PURCHASE_REQUIRED` `LIMIT_REACHED` `PAGINATION_DEPTH_EXCEEDED` `ADMIN_REQUIRED` `READ_ONLY_SESSION` `ORIGIN_BLOCKED` `CLIENT_BLOCKED` `ACTION_NOT_ALLOWED`	118
404	Resource not found	`RESOURCE_NOT_FOUND` `ROUTE_NOT_FOUND`	60
413	The request body is larger than this endpoint accepts, which is 1 MB for a JSON body. Refused from `Content-Length` before the body is read, so nothing was stored and the request can be split and resent. `error.maxBytes` carries the limit.	`PAYLOAD_TOO_LARGE`	8
429	Rate limit exceeded	`RATE_LIMITED` `DAILY_CAP_EXCEEDED` `MCP_DAILY_CAP_EXCEEDED` `PAGINATION_BURST` `REPORT_RATE_LIMITED`	133
500	Internal server error	`INTERNAL_ERROR`	133

Error codes

code is the family and never changes. When a request fails without a more specific situation, the reason is the family's default, listed here.

Code	Status	Default reason
	400	`INVALID_REQUEST`
	401	`AUTH_REQUIRED`
	403	`ACTION_NOT_ALLOWED`
	403	`PAGINATION_DEPTH_EXCEEDED`
	403	`PLAN_REQUIRED`
	404	`RESOURCE_NOT_FOUND`
	409	`CONFLICT`
	413	`PAYLOAD_TOO_LARGE`
	429	`DAILY_CAP_EXCEEDED`
	429	`MCP_DAILY_CAP_EXCEEDED`
	429	`RATE_LIMITED`
	429	`REPORT_RATE_LIMITED`
	429	`RATE_LIMITED`
	500	`INTERNAL_ERROR`
	503	`DEPENDENCY_UNAVAILABLE`

All 39 reasons

Every reason the API can send, by status: what happened, and what to do next. A reason is part of the published contract. New ones are added; none are renamed.

400Bad request3

A path, query or body field failed validation. details names each field and what was wrong with it.
What to doCorrect the named fields and send the request again.
The request body is not valid JSON.
What to doSend a JSON body with Content-Type: application/json.
The request is well-formed but asks for something the endpoint refuses; the message says what.
What to doChange the request as the message describes.

401Unauthorized: the credential10Read more

This endpoint needs a credential and none was sent.
What to doSend an API key in X-API-Key, or sign in.
No API key was sent.
What to doSend your key in the X-API-Key header.
The API key is not one we issued, or it has been deleted.
What to doCheck the key for a typo, or create a new one in your account.
The key was switched off by the account that owns it.
What to doRe-enable it in your account, or use another key.
The key has passed its expiry date.
What to doCreate a new key in your account.
This endpoint needs a signed-in session.
What to doSign in, then retry.
The session is no longer valid.
What to doSign in again.
The credential verified, but the account behind it no longer exists.
What to doSign in again, or contact support.
The one-time access link has expired or was already used.
What to doRequest a new link.
A proxy or marketplace credential was presented and does not verify.
What to doThrough a marketplace such as RapidAPI, contact the API provider: the proxy is misconfigured.

403Forbidden: the permission14Read more

The credential is valid and its plan is below what this endpoint needs. details.requiredTier names the plan.
What to doUpgrade the plan. A new key on the same plan will get the same answer.
The account behind this credential has been suspended.
What to doContact support. Rotating the key will not help.
The key is valid but no user account owns it, so account endpoints (/v1/me) have nothing to act on.
What to doUse a key created from your account.
The key is valid but no shop names it, so seller endpoints (/v1/vendor) have no shop to act for.
What to doName the key in Profile > Seller on the shop it should act for, then check GET /v1/vendor/shops.
The shop exists and has not been approved yet.
What to doWait for approval. Nothing needs to be sent again.
The resource exists and belongs to another account or shop.
What to doUse an id your account owns.
The download belongs to a product this account has not bought.
What to doBuy the product, then retry.
The plan's allowance for this kind of item is used up.
What to doRemove one, or upgrade for a larger allowance.
The plan does not page this deep into a list.
What to doNarrow the list with filters, or upgrade for deeper paging.
Staff-only endpoint.
What to doSign in with a staff account.
This is an impersonation session, which may look but never change anything.
What to doMake the change from your own account.
A browser request carried a GunSpec origin without the signature our own apps send.
What to doCall the API with an API key.
This client, user agent or address is blocked.
What to doContact support if you think this is a mistake.
The action is not permitted on this resource; the message says why.
What to doDo not retry unchanged.

404Not found2

The path is right and no record has that id.
What to doCheck the id. The list and search endpoints return valid ones.
No endpoint answers this method and path.
What to doCheck the path and method against the API reference.

409Conflict1

The request conflicts with existing data, such as a slug already in use.
What to doChange the conflicting value and retry.

413Payload too large1

The request body is larger than this endpoint accepts. maxBytes carries the limit.
What to doSplit the request into smaller ones.

429Slow down5Read more

Too many requests this minute for the plan.
What to doWait for Retry-After seconds, then retry.
The plan's daily request allowance is used up. It resets at midnight UTC.
What to doWait for the reset, or upgrade for a larger allowance.
The plan's daily allowance for calls through the MCP server is used up. It resets at midnight UTC; direct API requests still count against the plan's own allowance.
What to doWait for the reset, call the API directly, or upgrade for a larger MCP allowance.
Too many sequential pages in a short time.
What to doSlow the walk down, or use a larger per_page.
A data report for this section was already filed in the last 24 hours.
What to doWait a day, or add to the report already filed.

500Our side1

Something failed on our side. It has been logged against request_id.
What to doRetry with backoff. Quote request_id if it persists.

503Temporarily unavailable2

A service this endpoint depends on is temporarily unavailable.
What to doRetry after a short wait.
The API is paused for maintenance.
What to doWait for Retry-After seconds, then retry.

Request IDs

Every response carries an X-Request-Id header and every error body echoes it as request_id. Quote it to support: it finds the request in our logs.

Retry-After

Retry-After is the only rate-limit header the API sends: on a 429 it is the seconds to wait before the next allowed request (60 for the per-minute limit, 3600 for the daily cap), and a 503 during maintenance carries it too. There is no X-RateLimit-Remaining; the edge limiter reports whether a request was allowed, not how much of the window is left. For consumption against your monthly allowance, poll GET /v1/me/usage.