Errores y límites
Todos los errores tienen la misma forma y un código HTTP estable. Los límites protegen a todos los usuarios de la API.
Formato
json
{ "error": "prices es obligatorio si el evento no es gratis" }El mensaje está en español y es legible: muéstralo o regístralo tal cual. Para decidir qué hacer, usa el código.
Códigos
| Código | Significa | Qué hacer |
|---|---|---|
400 | Regla del evento no cumplida (de pago sin precios, fin antes del inicio, moneda o zona no válida…) | Corrige los datos; no reintentes igual |
401 | Clave o token ausente, inválido o revocado, o quien la creó ya no gestiona la empresa | Revisa la cabecera Authorization o crea otra clave |
403 | Falta el scope (La clave no tiene el permiso events:write) | Crea una clave o pide un token con ese permiso |
404 | El recurso no existe, es de otra empresa o de otro modo (live/test) | No se distingue a propósito |
409 | Conflicto: externalId ya existe en POST, entradas ya vendidas en un precio que quitas, límite de claves o webhooks | Usa el upsert o ajusta el cambio |
413 | Imagen demasiado grande | Hasta 10 MB |
422 | Formato inválido: falta un campo obligatorio, tipo incorrecto, dirección no encontrada o póster que no se pudo descargar | Corrige los datos |
429 | Demasiadas peticiones | Espera y reintenta con backoff |
5xx | Error nuestro | Reintenta con backoff; el upsert es idempotente |
Los errores de OAuth siguen el RFC 6749 (invalid_client, invalid_grant…); los ves en Autenticación.
Límites
| Qué | Límite |
|---|---|
Peticiones a /v1 y al MCP | 60 por minuto por clave o por permiso OAuth |
GET /v1/events | limit hasta 100 |
GET /v1/events/:id/tickets | limit hasta 500 |
| Pósters | JPG, PNG o WebP, hasta 10 MB |
| Claves de API activas | 2 (gratis) o 10 (PRO) por empresa |
| Webhooks | 10 por empresa |
| Feeds | 10 por empresa; archivos hasta 3 MB |
| Apps OAuth | 10 por persona |
| Eventos de prueba | Se borran a los 7 días |
| Access token OAuth | 1 hora; refresh token, 90 días |
Reintentos recomendados
- Reintenta solo
429y5xx, con espera exponencial (1 s, 2 s, 4 s…). - Con el upsert (
PUT /v1/events/external/…) reintentar nunca duplica eventos.