Errors

Application-layer errors (validation, conflicts, rate limits, generation quota, upstream provider failures, unexpected server errors) are returned in RFC 7807 problem-details format with Content-Type: application/problem+json and a JSON body with a consistent shape.

Authentication challenges are an exception. A 401 from the API-key auth handler — missing key, unknown key, revoked key, disabled owner, or a per-IP throttle hit — is a bare WWW-Authenticate: Bearer challenge with no JSON body. The status alone is the signal; the body is intentionally empty so failure modes do not disclose which condition applied.

Problem-details shape

{
  "type": "VALIDATION_ERROR",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "The 'name' field is required."
}

Status codes

400 — bad request

The request body or query parameters failed validation. Read detail to see which field or constraint caused the rejection. Fix the request before retrying.

The billing-checkout endpoint — POST /v1/billing/checkout-session — returns one specific typed 400 worth branching on:

401 — unauthorized

No valid API key was found, or the key was revoked, or the account owning the key is disabled. The response is a bare challenge with no JSON body — the status alone is the signal. Check that your Authorization: Bearer sf_xxxxxxxxxxxx header is present, correctly spelled, and uses a key that has not been revoked.

A 401 can also mean the per-IP auth-failure throttle has engaged. See rate limits and authentication.

402 — payment required

Your account has either exhausted its monthly generation allowance for the current period or attempted a generation profile (e.g. Researcher) that your tier does not include. The response body identifies the limit you hit, and the response carries X-Quota-Tier, X-Quota-Limit, X-Quota-Used, and X-Quota-Reset headers so callers can render upgrade prompts. Wait until X-Quota-Reset, switch to a permitted profile, or upgrade the account.

Generation kickoff endpoints (POST /v1/generations, POST /v1/generations/{id}/retry) emit two specific typed 402 values worth branching on:

403 — forbidden

The API key is valid, but it does not have permission to perform the requested action. This typically means the operation requires a role or permission your account does not hold.

Generation kickoff endpoints (POST /v1/generations, POST /v1/generations/{id}/update, POST /v1/generations/{id}/retry) emit one specific typed 403 worth branching on:

404 — not found

The resource does not exist, or it exists but belongs to a different account. SpecStep does not distinguish between "not found" and "found but not yours" — both return 404.

409 — conflict

The request is well-formed but conflicts with the current state of the resource. For example, attempting to start a generation when one is already running, or delivering a package that has already been delivered. Read detail for the specific conflict.

Generation kickoff endpoints (POST /v1/generations, POST /v1/generations/{id}/retry) emit additional typed 409 values worth branching on:

The retry endpoint — POST /v1/generations/{id}/retry — returns one of four specific type values when it fires a 409:

All four come back as application/problem+json with status 409, a title matching the uppercase code (e.g. RETRY_STATE_INVALID), and a detail describing the specific row.

The pause/resume/cancel endpoints — POST /v1/generations/{id}/pause, POST /v1/generations/{id}/resume, POST /v1/generations/{id}/cancel — return their own 409 codes when the requested transition is illegal for the generation's current state.

The documentation-migration commit endpoint — POST /v1/doc-migrations/commit (and the MCP commit_doc_migration tool) — returns its own 409 when the upload can't be placed unambiguously:

Note for parser-writers: the retry codes above use full URL type values (e.g. https://specstep.com/errors/retry_state_invalid); the pause/resume/cancel codes use bare uppercase strings (e.g. CONFLICT_STATE_TRANSITION). Both are emitted as-is — match on a normalized form if you need a single switch.

POST /v1/interviews/{id}/turns — when an Idempotency-Key collides with an in-flight submission, you get 409 with INTERVIEW_TURN_IN_FLIGHT, a Retry-After: 5 header, and the structured fields described in Structured error data (REST). When the original submission failed, retries with the same key get the cached error code (e.g. INTERVIEW_TURN_TIMEOUT) with replayed_from_cache: true in the extension data.

Structured error data (REST)

ProblemDetails responses on the interview-turn surface carry retry hints as extension fields on the body. The fields are stable across error codes:

Structured error data (MCP)

MCP JsonRpcError responses carry the same retry hints via the spec's data field. The data object always includes error_code and any of the fields above that apply. For example, an INTERVIEW_TURN_IN_FLIGHT error returns:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32000,
    "message": "INTERVIEW_TURN_IN_FLIGHT: A submission for interview <uuid> with this client_request_id is already being processed; retry the SAME id after a short wait.",
    "data": {
      "error_code": "INTERVIEW_TURN_IN_FLIGHT",
      "retryable": true,
      "retry_after_seconds": 5,
      "turn_committed": false,
      "client_request_id": "...",
      "interview_id": "..."
    }
  }
}

The catch-all -32603 Internal error is emitted without data — clients can't infer commit semantics from arbitrary unhandled exceptions, so we don't guess. Treat bare -32603 as "unknown state; safest to call get_interview(interview_id) to discover what actually happened."

Interview-turn error codes

Surfaces: POST /v1/interviews/{id}/turns (sync + async), GET /v1/interviews/turns/{jobId}, MCP submit_interview_turn (sync + async), MCP get_interview_turn_status. The error_code on a failed job's status, or in the data payload of an interview-turn error envelope, is one of:

429 — too many requests

The rate limit for this endpoint has been exceeded. Read the Retry-After header and wait that many seconds before retrying. See rate limits for the full retry protocol.

{
  "type": "RATE_LIMITED",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded; retry in 14s.",
  "retry_after_seconds": 14
}

500 — internal server error

Something went wrong on SpecStep's end. The detail field will contain a reference identifier you can include in a support ticket. Do not assume the operation succeeded — check the resource's state before retrying.

502 — bad gateway

An upstream LLM provider (Anthropic, OpenAI, or your bring-your-own provider) returned an error or timed out while servicing the request. The detail field describes the failure mode; the request is safe to retry once after a short wait, since SpecStep's own state was not modified.

The type on a 502 is one of the provider error codes below. Branch on it when you want to distinguish "wait and try again" from "the request itself is wrong."

503 — service unavailable

The only 503 in the API today is EXPLAIN_TIMEOUT — fired when a POST /v1/packages/{id}/explain cold call exceeds its ~75s wall-clock budget. This is SpecStep's own budget, not a network or gateway timeout — distinct from a 504 and retry-friendly. No cost is incurred when it fires, so a retry is safe. Branch on type; detail is advisory prose, not a stable string to match on.

{
  "type": "EXPLAIN_TIMEOUT",
  "title": "EXPLAIN_TIMEOUT",
  "status": 503,
  "detail": "The explanation took longer than 75s to generate. This usually means the upstream LLM is slow right now. Try again — most calls succeed within 30s."
}

Provider errors

These type values appear on 502 responses (and on the failure_reason of Failed generations whose underlying cause was an LLM provider). Use them to decide whether to retry, rotate a key, or fix the request.

Retryable vs non-retryable

Generation failure categories

GET /v1/generations/{id} responses include a typed failure_category field on terminal Failed rows — see REST walkthrough — failure categories for the full enum and the additive contract. It is not an HTTP error code; it describes why a 200 response shows state: "Failed".

Note that ReviewBudgetExhausted, RedraftNoProgress, ReviewLoopStalled, and CostBudgetExceeded are all content-quality / convergence outcomes, not transient system faults. Unlike NetworkTimeout or HostRestart, retrying the same intake at the same review profile produces the same result — adjust the intake, raise the review profile, or raise the cost cap before re-running.

The accompanying failure_reason string is sanitized — normalized to a short stable classifier (provider rate-limit, auth failure, transient, and similar) rather than echoed verbatim from the upstream provider. Raw provider messages can leak provider internals or request fragments containing PII, so the API never surfaces them. Treat failure_category as the primary programmatic surface; failure_reason is a human-readable hint, not a parseable contract — the exact strings are not stable. This sanitization applies wherever failure_reason appears: REST GET /v1/generations/{id}, the MCP get_generation and wait_for_generation tools, and webhook delivery bodies.

Endpoint-specific validation

These sections cover error semantics for endpoints whose validation logic is too specific to fold into the global "Status codes" table above. The canonical happy-path docs live on the feature pages — see REST walkthrough for the kickoff / clarification / delivery flows and Webhooks instead of polling for the dispatcher contract.

Mid-generation clarification

GET /v1/generations/{id}/clarifications and POST /v1/generations/{id}/clarifications/answers (added 2026-05-05) have their own validation cases worth calling out:

The pairing key between submitted answers and pending clarifications is the verbatim question string. Don't paraphrase or trim — copy the question text from the GET response unchanged. Answers whose question text doesn't match a pending clarification are accepted but ignored, which is rarely what callers intend.

Bug-report submission

POST /v1/bug-reports emits typed validation codes alongside the standard problem-details shape. All fire as 400 Bad Request.

GET /v1/bug-reports/{id} follows the same not-leak posture as the rest of the by-id surface: a foreign caller gets 404, not 403. The submitter sees the report; everyone else sees the same response a non-existent id would produce.

Feedback submission

Distinct from bug reports — feedback evaluates quality (was the interview good, is the package coherent), not broken behavior. See REST walkthrough — Quality feedback for the endpoint reference.

POST /v1/feedback emits typed validation codes in the standard problem-details shape. All fire as 400 Bad Request.

GET /v1/feedback/{id} returns 404 for foreign callers, without distinguishing "doesn't exist" from "isn't yours."

Feedback amendment

PATCH /v1/feedback/{id}/amend lets the original submitter self-correct free-form content while the row is still Open and within the amend window (10 minutes of submission). See REST walkthrough — Quality feedback for the field list. Both codes below fire as 400 Bad Request; a non-owner gets 404 (existence isn't leaked), not a typed code.

Webhook receivers

Webhook receivers run on your infrastructure, but the dispatcher's behavior shapes what you should return:

• 2xx — delivery considered successful. SpecStep stops retrying and stamps the subscription with the success status + HTTP code.
• 4xx — terminal subscriber rejection. SpecStep does NOT retry — the next event will be attempted, but this delivery is dropped. Use 4xx deliberately when you want SpecStep to stop hammering a misconfigured receiver.
• 5xx or transport failure — retried up to 3 times with exponential backoff (1s, 4s, 16s). After the final failure the delivery is logged + dropped (no DLQ in v1).

The X-SpecStep-Webhook-Delivery header is your dedup key. The same delivery id may arrive more than once if the dispatcher retries past your 200 response (network race), so design idempotently.

Reference document upload validation

POST /v1/interviews/{interviewId}/reference-documents rejects malformed uploads at the endpoint boundary before the service layer runs. All three cases return 400 Bad Request with the standard problem-details shape; the title is the stable signal.

The supplied filename is sanitized server-side rather than rejected: directory components are stripped (path-traversal mitigation), characters outside [A-Za-z0-9._- ] are replaced with _, leading dots are removed, and the result is capped at 200 characters. Callers see the sanitized name in the upload response and in audit logs — there is no error path for filename normalization.