Errors

Every error response uses the same JSON envelope and a stable error code. Use the code for branching logic — message is human-readable and may change. request_id is the value of the X-Request-Id header, useful when contacting support.

Envelope

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. 50 required.",
    "details": { "credits_required": 50 },
    "request_id": "01HZ8K..."
  }
}

Error code table

• 400 VALIDATION_ERROR — body / query / path failed zod validation. details.field_errors lists each issue.
• 400 EMPTY_PATCH — PATCH request had no recognized fields.
• 401 UNAUTHORIZED — missing or invalid bearer token. WWW-Authenticate header set.
• 402 INSUFFICIENT_CREDITS — async AI call needs more credits than the org has.
• 402 PAID_PLAN_REQUIRED — review simulation requires a paid plan.
• 403 FORBIDDEN — key lacks the required scope. details.required_scope names it.
• 403 NO_ORGANIZATION — key not bound to an organization (rare; happens on legacy keys).
• 404 NOT_FOUND — resource missing or not in your organization.
• 409 DUPLICATE — unique constraint violation (e.g. tracking the same keyword twice).
• 415 UNSUPPORTED_MEDIA_TYPE — POST/PATCH body wasn't JSON.
• 422 SOURCE_NOT_FOUND — localize_listing called with a source locale that doesn't exist yet.
• 422 NO_BILLING_ORG — project has no billing org (legacy data; contact support).
• 429 RATE_LIMITED — 120/min quota exceeded. Retry-After header set.
• 500 DB_ERROR — unexpected database error. Includes a request_id for support.
• 500 INTERNAL_ERROR — unhandled exception. Reported to our logs automatically.
• 502 ASO_API_ERROR — upstream App Store / Play Store data service failed.
• 504 REVIEW_FAILED — AI review simulation timed out or errored.

Example: validation error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "field_errors": [
        { "path": "store_type", "message": "Invalid enum value", "code": "invalid_enum_value" },
        { "path": "keyword", "message": "String must contain at least 1 character(s)", "code": "too_small" }
      ]
    },
    "request_id": "01HZ8..."
  }
}