Errores

La API devuelve errores en formato application/problem+json (RFC 9457). Todo error comparte una estructura estable y predecible:

{
  "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"
}

Campos

Campo	Descripción
type	URI estable que documenta el error (apunta a docs.skipo.com/errors/{code}).
title	Resumen legible del tipo de error.
status	Código HTTP.
detail	Descripción específica de esta ocurrencia.
code	Código estable legible por máquina — úsalo para ramificar tu lógica.
retryable	true si reintentar la misma petición puede tener éxito.
instance	Ruta de la petición que falló.
reason	Sub-código estable presente en algunos errores (p. ej. varios 422 unprocessable) que precisa qué regla de negocio falló — más fino que code. Ramificable igual que code. Ausente cuando no aplica.

consejo

Ramifica tu manejo de errores sobre code (y sobre reason cuando esté presente), nunca sobre title ni detail (que pueden cambiar de redacción o traducirse). code y reason son contratos estables.

Un mismo code puede cubrir varias causas; reason las distingue. Por ejemplo, un 422 unprocessable al pedir un precio sobre un mercado cerrado:

{
  "type": "https://docs.skipo.com/errors/unprocessable",
  "title": "Unprocessable request",
  "status": 422,
  "code": "unprocessable",
  "reason": "MARKET_CLOSED",
  "detail": "Market 'NVDASPV-CLP' is closed right now.",
  "retryable": false,
  "instance": "/v2/markets/NVDASPV-CLP/price?side=BUY"
}

Códigos comunes

code	HTTP	¿Reintentable?
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	sí
internal_error	500	sí

El catálogo completo de errores documenta los 22 códigos, cada uno con su propia página en docs.skipo.com/errors/{code} — la misma URI que aparece en el campo type de la respuesta.