The official error table in the Bitrix24 (Alaio) developer docs lists the codes and says almost nothing about what to do next. They fall into five families — authorization, permissions and scope, limits, malformed requests, server-side faults — and each has a different owner: some are fixed in portal settings, some only in code.

What does a Bitrix24 error response actually look like?

Every failed call returns an HTTP status and a small JSON body:

{ "error": "QUERY_LIMIT_EXCEEDED", "error_description": "Too many requests" }

error is the machine-readable code you branch on; error_description is a sentence, usually vaguer than the code, so logging only the description discards the one field you can reliably match on. The status matters too: 401 is "we do not know who you are", 403 is "we know, and you may not".

Which error codes mean an authorization problem?

NO_AUTH_FOUND (401) means the access token or webhook code is invalid — wrong, truncated, or from another portal. expired_token (401) is narrower and more common: the token was valid, its lifetime ended. invalid_grant appears when you exchange or refresh tokens and the credentials are not accepted — details in invalid_grant and expired tokens. invalid_client means the client data is wrong, or the application is not installed on that portal; see application not installed.

No portal setting fixes these — they are token-lifecycle problems inside the integration: store the refresh token, renew before use, re-run the install flow when renewal itself fails.

What do scope and permission errors mean?

Three 403s cover this ground and are easy to confuse. insufficient_scope / invalid_scope — the method belongs to a scope the token does not carry; webhook scopes are set when the key is created, application scopes in its card, and changing either means reissuing or reinstalling. INVALID_CREDENTIALS — token and scope are fine, but the user behind them lacks rights to that data: a webhook created by an employee who cannot see a pipeline will not read it through REST either. user_access_error — the application is installed, but an administrator restricted it to specific users. A fourth, ACCESS_DENIED, is different again: the REST API itself is unavailable, being offered on commercial plans only.

Which errors are about limits?

QUERY_LIMIT_EXCEEDED (503) is the rate limiter — a leaky-bucket counter per portal that drains at 2 requests per second with a burst allowance of 50 on most plans, 5 per second with 250 on Enterprise. Exceed it and calls are rejected until the counter falls; the remedy is fewer, larger calls — batch requests instead of loops — plus retry with growing delay. OPERATION_TIME_LIMIT (429) is a separate budget: accumulated execution time across ten one-minute baskets, with operating_reset_at naming the moment the oldest frees up. OVERLOAD_LIMIT (503) is a manual block from support and cannot be waited out. Full picture: query limit exceeded.

Which errors mean the request itself is wrong?

ERROR_METHOD_NOT_FOUND — the method name is misspelled or absent on that edition. INVALID_REQUEST (400) comes back when a call arrives over plain HTTP instead of HTTPS. In batch calls, ERROR_BATCH_METHOD_NOT_ALLOWED (405) means the method is not permitted inside a batch, ERROR_BATCH_LENGTH_EXCEEDED (400) that the packed parameters were too long. Validation errors from a specific method carry their own codes and a description naming the field — required fields are the usual culprit. INTERNAL_SERVER_ERROR and ERROR_UNEXPECTED_ANSWER (500) are server-side: retry once, and if they persist for one method with one input it is a support ticket, not a bug in your loop.

Which side of the fence is my error on?

Portal settings fix: webhook key scope, employee access rights, application access restrictions, plan availability. Code fixes everything else — token refresh, batching, retry with backoff, method names, HTTPS. Authorization and limits are always code; the portal has no dial to raise the rate.

If automation silently stops instead of returning an error, that is a different path: start with automations not running. If the application interface will not open at all, see the app iframe not loading.

How do I handle these errors from inside a workflow?

When a workflow calls an external service, you receive someone else's status codes. HTTP request GET/POST returns the response body, the status code and a Y/N success flag, so the workflow can branch on the status; Extract value from JSON by path pulls an error field out for a readable log entry, and Build JSON from fields assembles the outgoing payload. For calls that must not be lost, Reliable webhook retries failed attempts, lets you define which status codes count as success, and notifies chosen users if delivery ultimately fails. These cover outbound calls — they do not repair a portal's own authorization problems.

Where to go from here

Read the code, not the description, and decide which side of the fence the fix is on. The robot catalog covers outbound requests and response parsing; the webhooks guide explains the other direction. If your scenario is not covered, describe the task — we build the robot free and add it to the shared library.