API error codes

Format: RFC 7807 Problem Details Content-Type: application/problem+json Last updated: 2026-05-25

Every v1 error response carries a JSON body in the RFC 7807 shape and a stable type URI you can switch on without parsing strings.

{
  "type": "https://docs.vendu.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/api/v1/products",
  "errors": [
    { "field": "price", "code": "invalid_type", "message": "price must be a number" }
  ],
  "trace_id": "abc-123-…"
}

trace_id is included on every response — quote it in support tickets so the on-call engineer can pull the matching Sentry event.

Catalog

`type` slug	HTTP	When
`authentication-required`	401	No / malformed `Authorization` header.
`invalid-api-key`	403	Token revoked or doesn't match a tenant.
`insufficient-scope`	403	API key missing the required scope (e.g. `write`).
`rate-limit-exceeded`	429	Per-API-key window exhausted. `retry_after_sec` + `Retry-After` header set.
`validation-failed`	422	Request body / params failed schema validation. `errors[]` enumerates field problems.
`resource-not-found`	404	Resource missing or not accessible to this tenant.
`conflict`	409	Domain-level conflict (e.g. duplicate idempotency key).
`precondition-failed`	412	`If-Match` / `If-Unmodified-Since` failed.
`payload-too-large`	413	Body exceeds the route limit (e.g. bulk > 100 items).
`unsupported-media-type`	415	Wrong / missing `Content-Type`.
`method-not-allowed`	405	HTTP method not allowed on this path.
`internal-error`	500	Unexpected server error. `detail` is generic — use `trace_id` for triage.
`service-unavailable`	503	Downstream dependency (DB / Redis / QStash) degraded.

Bulk endpoints

POST /api/v1/{resource}/bulk returns 207 Multi-Status on partial failure and 200 / 422 on uniform success / failure. Each item result carries its own status and either data or error (a full Problem document).

Trace IDs in webhooks + crons

trace_id is included on outbound webhook envelopes (via the X-Vendu-Delivery-Id header) and on every Sentry event so a single identifier ties together HTTP, queue, and saga work.

{ "type": "https://docs.vendu.app/errors/validation-failed", "title": "Validation failed", "status": 422, "detail": "One or more fields are invalid.", "instance": "/api/v1/products", "errors": [ { "field": "price", "code": "invalid_type", "message": "price must be a number" } ], "trace_id": "abc-123-…" }

Catalog

`type` slug	HTTP	When
`authentication-required`	401	No / malformed `Authorization` header.
`invalid-api-key`	403	Token revoked or doesn't match a tenant.
`insufficient-scope`	403	API key missing the required scope (e.g. `write`).
`rate-limit-exceeded`	429	Per-API-key window exhausted. `retry_after_sec` + `Retry-After` header set.
`validation-failed`	422	Request body / params failed schema validation. `errors[]` enumerates field problems.
`resource-not-found`	404	Resource missing or not accessible to this tenant.
`conflict`	409	Domain-level conflict (e.g. duplicate idempotency key).
`precondition-failed`	412	`If-Match` / `If-Unmodified-Since` failed.
`payload-too-large`	413	Body exceeds the route limit (e.g. bulk > 100 items).
`unsupported-media-type`	415	Wrong / missing `Content-Type`.
`method-not-allowed`	405	HTTP method not allowed on this path.
`internal-error`	500	Unexpected server error. `detail` is generic — use `trace_id` for triage.
`service-unavailable`	503	Downstream dependency (DB / Redis / QStash) degraded.