Errores comunes

Toda respuesta de error tiene el mismo envelope, con un code estable (programa contra él) y un message legible (puede cambiar; no lo parsees):

{ "error": { "code": "TICKET_NOT_FOUND", "message": "Ticket not found" } }

Las respuestas de error incluyen además el header x-request-id. Guárdalo en tus logs y compártelo con alpadevs al reportar un problema.

Códigos

HTTP	code	Cuándo	Qué hacer
400	VALIDATION_FAILED	Body o query no cumplen el schema (límites, tipos, UUIDs, fechas sin zona).	Corrige el request. El mensaje no detalla el campo: valida contra las tablas de cada endpoint.
401	KEY_INVALID	Llave ausente, malformada, revocada o proveedor desactivado.	Revisa la configuración; no reintentes a ciegas.
403	EXPERIENCE_NOT_LINKED	La experiencia no está enlazada a tu proveedor (o no existe).	Pide a alpadevs el enlace del evento y confirma el experienceId.
404	TICKET_NOT_FOUND	externalRef inexistente en esa experiencia.	Verifica el externalRef y que el bulk lo haya aceptado.
409	REDEEMED_CONFLICT	void sobre un boleto que ya entró por la puerta.	No se revierte por API; consúltalo con alpadevs si es un error operativo.
429	RATE_LIMITED	Más de 60 requests por minuto en esa ruta con esa llave.	Espera al siguiente minuto; agrupa en bulk.
500	INTERNAL	Error nuestro.	Reintenta con backoff exponencial; todos los endpoints son idempotentes.

Además:

• Una ruta inexistente responde 404 con code: "INTERNAL" y message: "Route not found".
• Los rechazos por fila del bulk (rejected[].reason) no son errores HTTP: el request responde 200. Su tabla está en la referencia del bulk.

Ejemplos

{ "error": { "code": "VALIDATION_FAILED", "message": "Validation failed" } }

{ "error": { "code": "KEY_INVALID", "message": "Missing bearer API key" } }

{ "error": { "code": "EXPERIENCE_NOT_LINKED", "message": "Experience is not linked to this provider" } }

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

Estrategia de reintentos recomendada

Respuesta	Reintentar
429, 500, timeout de red	Sí, con backoff exponencial y jitter (p. ej. 1 s, 2 s, 4 s… tope 60 s).
400, 401, 403, 404, 409	No: corrige la causa.

Como el bulk y el void son idempotentes, reintentar un request que pudo haberse aplicado nunca duplica datos.