Errores

Los errores devuelven un cuerpo JSON con un campo error y, a menudo, un message con más detalle:

{
  "error": "You haven't set up a wallet address for the Polygon network",
  "message": "Please configure a Polygon-specific wallet in your merchant settings before accepting payments on this network.",
  "network": "polygon"
}

Códigos de estado

Código	Significado
400	la solicitud se rechazó, lea error
401	credenciales ausentes o no válidas
404	el endpoint no existe, o el recurso no existe en los endpoints que lo usan
500	algo falló en el servidor

Un ID de pago desconocido devuelve 500

Leer un pago que no existe devuelve 500, no 404:

{ "success": false, "error": "Failed to query payment status" }

Esto afecta a los endpoints de lectura de pagos y de depósitos. Otros endpoints sí devuelven 404 para un recurso que no existe, así que el comportamiento no es coherente en toda la API. Se documenta porque es lo que ocurre hoy: no interprete un 500 en estas rutas como señal segura de una caída del servicio. Compruebe antes el ID.

Como pasar de 500 a 404 cambiaría el código de estado de un resultado existente, cuenta como un cambio incompatible según nuestra política de versionado y no llegará a v1 sin previo aviso.

Reintentos

Las respuestas 500 de los endpoints de lectura se pueden reintentar sin riesgo.

Reintentar una escritura solo es seguro si el servidor puede reconocer la repetición. Envíe una cabecera Idempotency-Key, o al menos el mismo orderId. Consulte Reintentar de forma segura.