Fehlerbehandlung

Jeder Fehler ist ein JSON-Umschlag mit einem stabilen code, einem genaueren reason und einer request_id. Verzweige auf code und reason, nie auf message, dessen Wortlaut sich ändern kann. Diese Seite wird aus der OpenAPI-Spezifikation der API und ihrer Reason-Registry erzeugt.

Der Umschlag

Jede Nicht-2xx-Antwort hat diese Form, und success ist immer 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}

codestringerforderlich
Machine-readable error code, e.g. NOT_FOUND, RATE_LIMITED, SUBSCRIPTION_REQUIRED. Branch on this, never on message.
reasonenumerforderlich
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.
messagestringerforderlich
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.

Statuscodes

Die HTTP-Status, die ein Fehler tragen kann, die Situationen dahinter und wie viele Endpunkte ihn deklarieren.

Status	Beschreibung	Gründe	Endpunkte
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

Fehlercodes

code ist die Familie und ändert sich nie. Schlägt eine Anfrage ohne genauere Situation fehl, ist der Grund der Standard der Familie, hier gelistet.

Code	Status	Standardgrund
	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`

Alle 39 Gründe

Jeder reason, den die API senden kann, nach Status: was passiert ist und was als Nächstes zu tun ist. Ein Grund ist Teil des veröffentlichten Vertrags: neue kommen hinzu, keiner wird umbenannt.

400Ungültige Anfrage3

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

401Unauthorized: das Credential10Mehr lesen

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

403Forbidden: die Berechtigung14Mehr lesen

The credential is valid and its plan is below what this endpoint needs. details.requiredTier names the plan.
Was tunUpgrade the plan. A new key on the same plan will get the same answer.
The account behind this credential has been suspended.
Was tunContact 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.
Was tunUse 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.
Was tunName 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.
Was tunWait for approval. Nothing needs to be sent again.
The resource exists and belongs to another account or shop.
Was tunUse an id your account owns.
The download belongs to a product this account has not bought.
Was tunBuy the product, then retry.
The plan's allowance for this kind of item is used up.
Was tunRemove one, or upgrade for a larger allowance.
The plan does not page this deep into a list.
Was tunNarrow the list with filters, or upgrade for deeper paging.
Staff-only endpoint.
Was tunSign in with a staff account.
This is an impersonation session, which may look but never change anything.
Was tunMake the change from your own account.
A browser request carried a GunSpec origin without the signature our own apps send.
Was tunCall the API with an API key.
This client, user agent or address is blocked.
Was tunContact support if you think this is a mistake.
The action is not permitted on this resource; the message says why.
Was tunDo not retry unchanged.

404Nicht gefunden2

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

409Konflikt1

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

413Body zu groß1

The request body is larger than this endpoint accepts. maxBytes carries the limit.
Was tunSplit the request into smaller ones.

429Langsamer5Mehr lesen

Too many requests this minute for the plan.
Was tunWait for Retry-After seconds, then retry.
The plan's daily request allowance is used up. It resets at midnight UTC.
Was tunWait 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.
Was tunWait for the reset, call the API directly, or upgrade for a larger MCP allowance.
Too many sequential pages in a short time.
Was tunSlow the walk down, or use a larger per_page.
A data report for this section was already filed in the last 24 hours.
Was tunWait a day, or add to the report already filed.

500Unsere Seite1

Something failed on our side. It has been logged against request_id.
Was tunRetry with backoff. Quote request_id if it persists.

503Vorübergehend nicht verfügbar2

A service this endpoint depends on is temporarily unavailable.
Was tunRetry after a short wait.
The API is paused for maintenance.
Was tunWait for Retry-After seconds, then retry.

Request-IDs

Jede Antwort trägt einen X-Request-Id-Header, jeder Fehlerkörper wiederholt ihn als request_id. Nenne ihn dem Support: er findet die Anfrage in unseren Logs.

Retry-After

Retry-After ist der einzige Rate-Limit-Header der API: bei 429 die Sekunden bis zur nächsten erlaubten Anfrage (60 beim Minutenlimit, 3600 bei der Tagesgrenze), und ein 503 während Wartung trägt ihn ebenfalls. Es gibt kein X-RateLimit-Remaining; der Edge-Limiter meldet, ob eine Anfrage erlaubt war, nicht wie viel vom Fenster übrig ist. Den Verbrauch gegen dein Monatskontingent liefert GET /v1/me/usage.