Errors and Rate Limits

Top-level Portal API failures use one envelope:

{
  "ok": false,
  "error": {
    "code": "API_KEY_REQUIRED",
    "message": "A Synthwav Portal API key is required.",
    "requestId": "f65d9849-4c74-41f6-b386-72bd0dc83d78"
  }
}

Include requestId when contacting SynthwavLabs about a failed request.

HTTP statuses

Status	Common codes	Action
`400`	`QUERY_REQUIRED`, `INVALID_CURSOR`, `INVALID_TOKEN_ID`, `BATCH_TOO_LARGE`	Correct the request.
`401`	`API_KEY_REQUIRED`, `API_KEY_INVALID`	Supply a valid active key.
`403`	`INSUFFICIENT_SCOPE`	Request the required partner scope.
`404`	`TOKEN_NOT_FOUND`	Search again and use a canonical identity.
`409`	`CURSOR_STALE`, `REGISTRY_CHANGED`	Restart the search or retry the request.
`429`	`RATE_LIMIT_EXCEEDED`	Wait until the indicated reset time.
`503`	`PARTNER_AUTH_UNAVAILABLE`, `PARTNER_RATE_LIMIT_UNAVAILABLE`, `REGISTRY_UNAVAILABLE`, `STEWARD_DATA_UNAVAILABLE`	Retry with backoff. The API fails closed.

Rate-limit headers

Authorized requests include:

Header	Meaning
`X-RateLimit-Limit`	Maximum requests in the active partner window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Window reset time in Unix seconds.
`Retry-After`	Seconds to wait after a `429` response.

Limits apply to the partner, not the caller IP. Multiple keys for the same partner and tier share the same request window.

Use bounded exponential backoff for 429 and retryable 503 responses. Do not retry invalid requests, invalid keys, missing scopes, or missing tokens without correcting the cause.