Códigos de error
Un solo sobre para todos los fallos:
{ "error": { "code": "invalid_request", "message": "…" } }
| HTTP | code |
Cuándo | Qué hacer |
|---|---|---|---|
| 401 | missing_api_key |
Sin cabecera Authorization: Bearer sk_… ni X-API-Key |
Añada la clave |
| 401 | invalid_api_key |
Clave revocada, desconocida o cuenta inactiva | Revise la clave y el estado de la cuenta |
| 403 | insufficient_scope |
La clave no tiene ese derecho (pagar, por ejemplo) | Emita una clave con el alcance correcto |
| 403 | client_inactive |
La cuenta no está validada, o está suspendida | Termine el expediente KYB |
| 403 | not_live |
Cuenta aún no abierta al modo real | Use una clave sk_test_ mientras tanto |
| 404 | not_found |
Recurso inexistente — o no suyo | Revise el identificador |
| 409 | already_exists |
Duplicado (referencia ya usada) | Lea el recurso existente |
| 409 | precondition_failed |
El estado no permite la operación | Consulte el recurso, corrija el encadenamiento |
| 409 | concurrent_request |
Mismo Idempotency-Key, cuerpo distinto |
No reutilice una clave para dos operaciones |
| 422 | invalid_request |
Cuerpo inválido (campo, importe, activo) | El message nombra el campo culpable |
| 422 | insufficient_funds |
Saldo insuficiente para este pago | Consulte GET /v1/balances |
| 429 | — | 300 peticiones/minuto superadas | Respete la cabecera Retry-After |
| 502 | upstream_error |
Una dependencia ha fallado | Reenvíe con el mismo Idempotency-Key |
| 503 | temporarily_unavailable |
Indisponibilidad pasajera | Reenvíe con backoff |
Reenviar sin riesgo
Los 502 y 503 se reenvían siempre con el mismo Idempotency-Key: si la primera petición
había llegado a buen puerto del lado del servidor, usted recupera su resultado en vez de crear un
duplicado.
Un
502no quiere decir que no haya pasado nada. Dice que una dependencia no respondió, no que la operación no exista. Es exactamente la situación para la que existe la idempotencia: reenvíe, no vuelva a crear.
not_found sobre un recurso que existe
La API responde 404 también cuando el recurso pertenece a otro comercio: nunca deduzca la
existencia de un recurso a partir de un 404.
Un cuerpo rechazado no es un campo ignorado
Un campo desconocido en un cuerpo JSON se ignora en silencio, no se rechaza. Una errata en el
nombre de un campo opcional no produce por tanto ningún error: produce una operación creada sin lo
que usted creía haber enviado. Relea los nombres en la referencia en lugar
de fiarse de la ausencia de un 422.