Errors

The API returns errors in application/problem+json format (RFC 9457). Every error shares a stable, predictable structure:

{
  "type": "https://docs.skipo.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "This operation requires a signed request (X-API-Key header + signed JWT).",
  "code": "unauthorized",
  "retryable": false,
  "instance": "/v2/withdrawals"
}

Fields

Field	Description
type	Stable URI documenting the error (points to docs.skipo.com/errors/{code}).
title	Human-readable summary of the error type.
status	HTTP status code.
detail	Description specific to this occurrence.
code	Stable, machine-readable code — use it to branch your logic.
retryable	true if retrying the same request may succeed.
instance	Path of the request that failed.

tip

Branch your error handling on code, not on title or detail (which may be reworded or translated). The code is a stable contract.

Common codes

code	HTTP	Retryable?
unauthorized	401	no
invalid_signature	401	no
insufficient_scope	403	no
not_found	404	no
validation_error	400	no
unprocessable	422	no
rate_limited	429	yes
internal_error	500	yes

The full error catalog documents all 22 codes, each with its own page at docs.skipo.com/errors/{code} — the same URI that appears in the response's type field.