Guías

Errores

Los errores usan los códigos de estado HTTP estándar y un código estable que puedes evaluar.

400 Bad Request

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is not valid.",
    "details": [
      {
        "path": "amount",
        "message": "Too many decimals for USD"
      }
    ]
  },
  "request_id": "req_01J9ZQ3K5W8X2N4M6P7R9S1T3V"
}

Cada respuesta tiene una cabecera X-Request-Id igual a request_id. Aparece en el registro de peticiones del panel; menciónala si contactas con soporte.

Códigos de error

401	`UNAUTHENTICATED` Clave de API ausente, mal formada, revocada o caducada.
403	`FORBIDDEN_SCOPE` La clave no tiene el permiso que necesita esta operación.
403	`WORKSPACE_SUSPENDED` El workspace está suspendido o archivado.
404	`NOT_FOUND` El recurso no existe, pertenece a otro workspace o al otro modo (live/prueba).
400	`VALIDATION_ERROR` El cuerpo o la query no son válidos. details lista cada campo.
400	`UNSUPPORTED_ASSET` El activo está desactivado o tu workspace no lo acepta.
400	`NO_WALLET_FOR_ASSET` No hay una wallet verificada para la red de ese activo.
400	`AMOUNT_BELOW_MINIMUM` El importe convertido a ese activo está por debajo de su mínimo.
503	`RATES_UNAVAILABLE` Las tasas de cambio no están disponibles en este momento. Reintenta en unos segundos.
409	`IDEMPOTENCY_MISMATCH` Este Idempotency-Key se usó antes con otra petición.
409	`IDEMPOTENCY_IN_PROGRESS` Una petición con este Idempotency-Key sigue en curso.
409	`INVALID_STATE` El recurso no puede hacer esto en su estado actual (p. ej. cancelar una factura pagada).
429	`RATE_LIMITED` Demasiadas peticiones. Espera los segundos de Retry-After.
413	`PAYLOAD_TOO_LARGE` El cuerpo supera los 64 KB.
403	`TEST_MODE_ONLY` Este endpoint solo funciona con claves de prueba.
403	`PLAN_LIMIT_REACHED` Tu plan no permite más de este recurso. details incluye kind, limit y current. Mejora el plan o libera alguno.
403	`WORKSPACE_RESTRICTED` El workspace tiene un statement de comisiones vencido: no puede crear facturas, links ni productos hasta pagarlo.
500	`INTERNAL_ERROR` Algo falló de nuestro lado. Reintenta y menciona el request_id si persiste.

Reintentar con seguridad

Reintenta las respuestas 429, 503 y 500 con espera exponencial. Envía el mismo Idempotency-Key al reintentar un POST para no crear nunca la misma factura dos veces.