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":"Acme Co"}'
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.
• 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.
• 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).

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.