Códigos de error

API v0.1.0

En esta página

Todas las respuestas de error de la API siguen un formato uniforme.

Formato de respuesta

json

{ "detail": "código_o_mensaje" }

HTTP	Significado	Acción típica
400	Petición válida pero estado/timing inválido. Ej: `payment_expired`.	No reintentar. Crear nuevo recurso o cambiar request.
401	Falta autenticación o `sk_` inválida.	Verificar header `Authorization` o `client_secret`.
403	Autenticado pero sin permisos: `invalid_client_secret`, `no_default_account`.	No reintentar con la misma credencial.
404	Recurso no existe o no pertenece al merchant.	Verificar `intent_id`.
409	Transición de estado inválida: `invalid_state:<estado>`.	Estado actual no permite la operación.
422	Validación de datos: formato venezolano inválido, `idempotency_key_mismatch`, etc.	Corregir body y reintentar.
500	Error interno del servidor.	Reintentar con backoff exponencial (1s, 2s, 4s, 8s…).
503	Servicio temporalmente no disponible.	Reintentar con backoff.

detail	Endpoint	Causa	Solución
`invalid_api_key`	cualquiera	sk_ revocada o inexistente.	Solicitar nueva.
`idempotency_key_mismatch`	`POST /v1/payments`	Misma key, body distinto.	Usar key nueva para body distinto.
`invalid_idempotency_key`	`POST /v1/payments`	Formato inválido (>100 chars o caracteres no permitidos).	Usar UUID v4 o similar.
`payment_expired`	`POST .../confirm`	>15 min desde creación.	Crear nuevo intent.
`invalid_client_secret`	`POST .../confirm`	client_secret no matchea el intent.	Verificar pareo correcto.
`invalid_state:<estado>`	`POST .../confirm`, `.../cancel`	Estado actual no permite la operación.	No reintentar; estado terminal.
`payment_intent_not_found`	varios	intent_id no existe o no es del merchant autenticado.	Verificar valor.