Códigos de error

La API usa códigos HTTP estándar. Esta tabla cubre los errores propios de la capa de la API PSP; además, algunos errores del core se propagan tal cual con su propio código.

Código	Significado	Causa habitual
400	Bad Request	Body/params inválidos (falla de validación), x-idempotency con menos de 5 caracteres, o la cuenta no tiene el vínculo con el core resuelto.
401	Unauthorized	Firma inválida, faltante o con timestamp fuera de la ventana de 5 minutos. Ver Troubleshooting de firma.
403	Forbidden	IP no permitida para tu key, o el servicio del endpoint no está habilitado para tu key.
405	Method Not Allowed	Método HTTP no soportado para ese path.
500	Internal Server Error	Conflicto de idempotencia (reusaste una clave x-idempotency de otra operación) o error del core propagado.

Formato de respuesta de error

{
  "status": 400,
  "error": "mensaje legible del error",
  "data": null
}

Las fallas de validación (400) incluyen en error los mensajes concatenados de los campos inválidos.

Conflicto de idempotencia

Si reusás una clave x-idempotency que ya corresponde a otra operación, la API responde 500 con:

{
  "success": false,
  "error": "Operation with idempotency key \"mi-clave-123@...\" already exists"
}

La operación con esa clave ya existe. Consultá su estado con GET /api/v1/operation/:operation_id en vez de reintentar con la misma clave. Ver Idempotencia.

Checklist rápido

• 401 → revisá signature_key, signature_secret, el canonical string (orden de claves del body, host, headers firmados) y que el timestamp esté en milisegundos y dentro de los 5 minutos.
• 403 → confirmá que salís desde una IP autorizada y que tu key tiene habilitado el servicio del endpoint.
• 400 por idempotencia → el header x-idempotency debe tener al menos 5 caracteres.
• 500 "already exists" → estás reusando una clave de idempotencia; generá una única por operación.
• Sin mensajes por WebSocket → validá la URL, las credenciales, el owner/cuenta y que el servicio de notificaciones esté habilitado. Ver Notificaciones.