Errores

El código de estado HTTP indica el tipo de problema. El cuerpo JSON dice exactamente qué pasó y, si afecta a un campo, cuál.

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "consent: must be true: confirm the guest agreed to data processing",
    "param": "consent"
  },
  "request_id": "req_0d4d15b86c484738b46b"
}

error.typestring: Categoría general: invalid_request_error, authentication_error, permission_error, idempotency_error, rate_limit_error, api_error.
error.codestring: Código estable y legible por máquina, por ejemplo member_not_found. Toma decisiones según este campo, no según el mensaje.
error.messagestring: Una frase para el desarrollador. Puede cambiar; no la analices.
error.paramstring: El campo de la petición al que se refiere el error, si lo hay.
request_idstring: También viene en la cabecera X-Request-Id de cada respuesta. Inclúyelo cuando nos escribas.

Parámetro	Tipo	Descripción
error.type	string	Categoría general: `invalid_request_error`, `authentication_error`, `permission_error`, `idempotency_error`, `rate_limit_error`, `api_error`.
error.code	string	Código estable y legible por máquina, por ejemplo `member_not_found`. Toma decisiones según este campo, no según el mensaje.
error.message	string	Una frase para el desarrollador. Puede cambiar; no la analices.
error.param	string	El campo de la petición al que se refiere el error, si lo hay.
request_id	string	También viene en la cabecera `X-Request-Id` de cada respuesta. Inclúyelo cuando nos escribas.

Códigos de estado

Estado	Significado	Qué hacer
200, 201	Éxito. 201 indica que se creó algo nuevo.
400	La petición está mal formada o un campo no es válido.	Corrige la petición. Si repites el mismo cuerpo, obtendrás la misma respuesta.
401	Sin clave, clave desconocida o clave revocada.	Revisa la clave.
402	La petición es válida, pero no se puede ejecutar, por ejemplo por saldo insuficiente.	Muestra el mensaje al cliente; el cuerpo trae los detalles.
403	A la clave le falta el permiso que necesita esta llamada.	Usa una clave con el permiso indicado en el mensaje.
404	El socio, la transacción, el plato o el pedido no existe en este local.	Revisa el identificador.
409	Conflicto: número de tarjeta ocupado, cambio de estado no permitido o el saldo cambió durante la llamada.	Lee el código. Con `balance_conflict`, reintenta con el mismo `external_id`.
429	Demasiadas peticiones.	Espera los segundos que indica `Retry-After`.
500, 502, 503	Algo falló de nuestro lado.	Reintenta con espera progresiva y el mismo `external_id` o `Idempotency-Key`. Nada se aplica dos veces.

Códigos frecuentes

Código	Cuándo
parameter_invalid	Falta un campo o tiene un formato incorrecto. Mira `param`.
member_not_found	Ningún socio coincide con el número de tarjeta, el código de barras, el teléfono o el id.
card_number_taken	Otro socio de este local ya tiene este número de tarjeta.
insufficient_balance	`redeem_amount` supera el saldo de cashback. `available` trae el saldo.
redeem_not_supported	El programa del socio no tiene saldo de cashback que canjear.
visit_not_supported	Se envió una visita para un programa de cashback. Envía un ticket con importe.
no_reward_available	El socio no tiene ninguna recompensa ganada para canjear.
transaction_not_found	No hay ninguna transacción con este `external_id`.
invalid_status_transition	El pedido no puede pasar de su estado actual al que enviaste.
missing_scope	La clave no tiene el permiso necesario.
hold_required	El local solo canjea cashback mediante reservas. Crea una con `POST /v1/holds`.
hold_expired, hold_captured, hold_released	La reserva ya no se puede usar. Crea una nueva.
register_id_required	El local numera los tickets por caja, así que `register_id` es obligatorio.
check_too_old	`closed_at` es más antiguo de lo que acepta el local.
scan_required	El local solo acepta esto para una tarjeta que esta clave escaneó poco antes.
refund_exceeds_check	La devolución supera lo que queda del ticket. `refundable` indica el resto.
adjustments_disabled	El local no permite ajustes de saldo a través de la API.
idempotency_key_reused	Se usó la misma `Idempotency-Key` con otro cuerpo.
rate_limited	Demasiadas peticiones desde esta clave.