AllyOneCRM / Errores y límites

Errores y límites

El formato de los errores de la API del CRM, qué significa cada estado, cuándo reintentar y cómo funcionan los límites.

Formato del error

La mayoría de las rutas responde con un único campo:

{ "error": "Contato não encontrado" }

Los errores de validación de esquema y los del propio servidor HTTP vienen en el formato completo:

{ "statusCode": 400, "error": "Bad Request", "message": "email: Required; password: Required" }

Para tratar ambos: lee body.message ?? body.error. El texto es para humanos, en portugués — decide por el estado HTTP, no por el mensaje.

Estados HTTP

Estado	Significa
`400`	Cuerpo o parámetro inválido.
`401`	Sin credencial, token expirado o inválido, o API key inválida, revocada o de otro tenant.
`403`	Sin permiso: el rol del usuario o el alcance de la API key no cubre la acción.
`404`	No encontrado — o de otro tenant.
`413`	Cuerpo de más de 256 MB.
`429`	Rate limit o bloqueo de login.
`500` · `502` · `503`	Error inesperado o indisponibilidad temporal (actualización en curso).

Cuándo reintentar

400, 403, 404, 413: no reintentes — corrige la solicitud.
401: renueva el token (/v1/auth/refresh) y reintenta una vez.
429: espera Retry-After segundos.
5xx o timeout: reintenta con backoff exponencial (1 s, 2 s, 4 s…). Al crear recursos, envía el header Idempotency-Key (hasta 200 caracteres) en el POST: un reintento con la misma clave y cuerpo devuelve la respuesta original con Idempotent-Replayed: true en vez de crear el recurso dos veces. Las claves duran 24 h por credencial; la misma clave con otro cuerpo devuelve 409. No se aplica a /v1/auth, rutas públicas ni subida de archivos.

Rate limit

Ruta	Límite
Por defecto	300 solicitudes / minuto — por usuario con sesión (JWT); por IP de origen con API key o sin autenticación
Login, registro, recuperación de contraseña y 2FA	5 / 15 minutos por IP

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41

Toda respuesta trae estos headers; el 429 trae también Retry-After. Además del límite por IP, 5 contraseñas erróneas seguidas para el mismo e-mail e IP bloquean nuevos intentos durante 15 minutos (429). Si varios de tus servicios salen por la misma IP pública, comparten el límite — centraliza las llamadas.

Tamaños y paginación

Cuerpo de solicitud y subida de CSV: hasta 256 MB.
Listas paginadas por page y pageSize (por defecto 50, máximo 100); la respuesta trae total y totalPages.