AllyOneCRM / Errors and limits

Errors and limits

The shape of CRM API errors, what each status means, when to retry a call and how the limits work.

Error format

Most routes respond with a single field:

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

Schema validation errors and errors from the HTTP server itself come in the full shape:

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

To handle both: read body.message ?? body.error. The text is for humans, in Portuguese — branch on the HTTP status, not on the message.

HTTP status codes

Status	Means
`400`	Invalid body or parameter.
`401`	No credentials, expired or invalid token, or an API key that is invalid, revoked or belongs to another tenant.
`403`	No permission: the user's role or the API key's scope doesn't cover the action.
`404`	Not found — or belongs to another tenant.
`413`	Body above 256 MB.
`429`	Rate limit or login lockout.
`500` · `502` · `503`	Unexpected error or temporary unavailability (deployment in progress).

When to retry

400, 403, 404, 413: don't retry — fix the request.
401: refresh the token (/v1/auth/refresh) and retry once.
429: wait Retry-After seconds.
5xx or timeout: retry with exponential backoff (1 s, 2 s, 4 s…). When creating resources, send an Idempotency-Key header (up to 200 characters) on the POST: a retry with the same key and body returns the original response with Idempotent-Replayed: true instead of creating the resource twice. Keys last 24 h per credential; the same key with a different body returns 409. Not applied to /v1/auth, public routes and file uploads.

Rate limit

Route	Limit
Default	300 requests / minute — per user on a session (JWT); per source IP with an API key or unauthenticated
Login, sign-up, password recovery and 2FA	5 / 15 minutes per IP

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

Every response carries these headers; a 429 also carries Retry-After. On top of the per-IP limit, 5 consecutive wrong passwords for the same email and IP lock further attempts for 15 minutes (429). If several of your services go out through the same public IP, they share the limit — centralize the calls.

Sizes and pagination

Request body and CSV upload: up to 256 MB.
Lists are paginated by page and pageSize (default 50, maximum 100); the response carries total and totalPages.