Errors

Every error from the 2QUIC Marketplace API is an RFC 7807 problem document served with Content-Type: application/problem+json. Unlike successful responses, error bodies are flat: there is no {data, meta} envelope around them.

The problem document

A real response from POST /v1/leases when the requested epoch range overlaps an existing exclusive lease:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://docs.swqos.dev/errors/lease-slot-taken",
  "title": "Lease slot already booked",
  "status": 409,
  "detail": "Requested epoch range overlaps an existing lease for this validator.",
  "extensions": {
    "conflicting_lease_id": "01JXF6Y0Q8ZJ4T2M9R3W5B7DKE"
  }
}

Retry guidance at a glance

• 400, 401, 403, 404, 422: your request is wrong or the resource state does not allow the action. Retrying the same request will fail the same way. Fix the request or the workflow first.
• 409: a conflict with concurrent or existing state. Some are retryable (idempotency-conflict, extension-race, concurrent-rotation), most mean "pick something else".
• 429: rate limited. Honor Retry-After and the X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers. Limits are listed on the authentication page.
• 5xx: transient server or upstream failure. Retry with exponential backoff. Writes guarded by Idempotency-Key are safe to retry with the same key.

Error catalog

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

5xx Server errors

Booking conflicts in detail

The two booking 409s are deliberately distinct:

• lease-slot-taken is the exclusive-overlap conflict. There is one specific lease in your way, and when the API can resolve it you get its ID in extensions.conflicting_lease_id. A pending_payment lease holds the slot too, so a conflict can clear by itself if that booking goes unpaid past the 15-minute payment window.
• shared-capacity-full is the seat-pool conflict for mode: "shared". There is no single conflicting lease, the seat count is exhausted for at least one epoch in your range.

A practical booking loop: on lease-slot-taken or shared-capacity-full, re-fetch the validator's availability from GET /v1/validators/{id} and offer the trader the next free window. On shared-not-offered (422), fall back to an exclusive quote.

For extensions, extension-already-pending means your previous extension attempt produced a payment memo that has not settled yet. Pay it or wait for the sweep to roll it back, do not stack new attempts. extension-race is a pure concurrency artifact and is safe to retry once.

Idempotency error semantics

The three guarded POSTs (/v1/leases, /v1/leases/{id}/extend, /v1/validators/{id}/leases/{lease_id}/revoke) interact with errors in a specific way:

• Only 200/201 responses are cached and replayed (for 24 hours, byte-identical body required).
• An error response releases the key, so retrying with the same key re-runs the handler. This is the correct recovery path after a 5xx.
• 409 idempotency-conflict means a duplicate is in flight right now, retry after 1 second with the same key.
• 422 idempotency-key-reused means you changed the body under a used key, mint a new key.

Full mechanics on the authentication and rate limits page.