Errors

Every /v1/* error returns the same JSON shape, regardless of HTTP status. Switch on error.code (stable, machine-readable), never on the human message, which we may rephrase between releases.

Envelope

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "errors": [
        { "loc": ["body", "name"], "msg": "Field required", "type": "missing" }
      ]
    }
  },
  "request_id": "01HZK3X4P5MQR8AY..."
}

Field	Description
error.code	Stable identifier from the catalog below. Switch on this.
error.message	Human-readable summary. Safe to display to end users.
error.details	Code-specific structured data (validation paths, retry hints, etc). Optional.
request_id	Echoes the X-Correlation-ID response header. Quote this when you contact support.

Examples

A couple of the codes you’re most likely to hit during integration:

# Missing or wrong scope (403)
$ curl -i https://api.rankprompt.com/v1/brands \
    -H "Authorization: Bearer rp_live_READ_ONLY_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -X POST -d '{"name":"adidas","website":"https://www.adidas.com"}'
HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'write:brands' scope",
    "details": { "required_scope": "write:brands", "key_scopes": ["read:brands"] }
  },
  "request_id": "01HZK3..."
}

# Cross-tenant brand access (403)
$ curl https://api.rankprompt.com/v1/brands/other-workspace-brand-id \
    -H "Authorization: Bearer rp_live_YOUR_KEY"
{ "error": { "code": "brand_not_authorized", "message": "..." }, "request_id": "..." }

# Quota exhausted (429)
$ curl -i https://api.rankprompt.com/v1/brands -H "Authorization: Bearer rp_live_YOUR_KEY"
HTTP/1.1 429 Too Many Requests
{ "error": { "code": "request_quota_exceeded", "message": "Monthly request quota exceeded" }, "request_id": "..." }

Status code conventions

/v1 follows a small, deliberate set of status codes. Catalog entries are the canonical source; these conventions explain why each maps the way it does:

• 400 validation_error: caller mistake in the URL or service-layer logical validation: malformed query string, bad path param, exceeded a cap, or invalid state transition. details.errors[*] carries the field-level breakdown when produced by Pydantic.
• 422 body_validation_error: the JSON body parsed but didn’t match the endpoint’s schema (missing required field, wrong type, range violation, unknown extra field on extra="forbid" schemas). details.errors[*] has the per-field breakdown. This is the RFC 7231 standard for schema-mismatched payloads, so generated SDKs should map it to their “Unprocessable Entity” exception class.
• 422 invalid_*: the body parsed cleanly but a value is semantically invalid in a way the SDK should be able to branch on (currently only invalid_frequency for unsupported Schedule.frequency values). Treat these like a typed enum violation, not a generic validation failure: the error.code is stable, so SDKs can map it to a typed exception.
• 422 ai_platform_unsupported: an ai_platforms value is not one of the six engines (chatgpt, claude, gemini, grok, perplexity, ai_overviews). details.value names the rejected value, details.supported lists the accepted ones, and for a retired engine (chatgpt_search, claude_search) details.replacement names the engine that runs in its place. Send the replacement; reads still return the retired values on past results.
• 409 *_conflict / *_in_flight: request shape is fine, but it conflicts with current state (idempotency replay race, schedule already at cap, etc).
• 402 insufficient_credits: auth and validation passed, but the call cannot be billed against the customer’s plan. When a plan cap stopped it (brands, tracked keywords, rank checks per day and the like), details.reason is plan_limit and details also carries feature, limit, current_count, current_plan, plans, suggested_plan and can_subscribe (see below).
• 403 account_membership_required: the key was made in a team account its creator is no longer an active member of; details.account_id names that account. Retrying will not help: create a key in an account you belong to. See Team keys.
• 402 payment_failed: a purchase whose payment could not complete. details.reason says why (the payment token was spent, too small or in another currency), so an agent can ask its wallet for a new one.
• 409 payment_processing: the buyer paid and the purchase is still being applied. Repeat the same call shortly; it will not charge again.
• 429 request_quota_exceeded / rate_limit_exceeded: the call was rejected without running. Retryable after the window resets.
• 5xx: server-side. Safe to retry with the same Idempotency-Key (see the Idempotency page).

Plan limits and can_subscribe

A plan_limit 402 says who can lift the cap. details.can_subscribe is true only when the key acts in its creator’s own account, the capped plan is the creator’s own, and the key holds write:billing: then POST /v1/me/subscriptions can start the plan that lifts it. It is false when the plan belongs to someone else, a team account’s owner or the owner of the brand, so only they can upgrade.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your current plan allows up to 25 tracked keywords. Upgrade your plan to track more.",
    "details": {
      "reason": "plan_limit",
      "feature": "tracked_keywords",
      "current_plan": "starter",
      "limit": 25,
      "current_count": 25,
      "plans": [
        { "plan": "free", "limit": 10 },
        { "plan": "starter", "limit": 25 },
        { "plan": "pro", "limit": 100 },
        { "plan": "agency", "limit": 250 },
        { "plan": "agency_plus", "limit": 500 }
      ],
      "suggested_plan": "pro",
      "can_subscribe": true
    }
  },
  "request_id": "01HZK3..."
}

Past-due billing

403 api_subscription_past_due (the API plan’s payment failed) and 403 subscription_past_due (the plan’s payment failed, so it is suspended) are billing failures, not missing access. details.billing_url opens the Subscription page, where Manage billing updates the card; the next call after the payment clears goes through. details.upgrade_url still points at the API plans page. In a team account neither link is sent: the message says that the account’s owner updates billing.

{
  "error": {
    "code": "api_subscription_past_due",
    "message": "API subscription payment is past due. Update billing to continue.",
    "details": {
      "billing_url": "https://app.rankprompt.com/subscription",
      "upgrade_url": "https://app.rankprompt.com/developers?source=api",
      "docs_url": "https://rankprompt.com/docs/v1/errors/#past-due-billing"
    }
  },
  "request_id": "01HZK3..."
}

Catalog

The full list of codes the /v1 surface can return. New codes will only ever be added; existing codes will not change their HTTP status or stable id.

Need help? Capture the failing request_id and the time of the request, then email support@rankprompt.com. We can trace any single call end-to-end from that pair.