System Specs & Limits

1. Technical Limits Matrix

Hard limits that apply to every tenant. Per-plan allowances (endpoints, requests per minute, monthly volume, payload size per endpoint, log retention) are in section 4.

2. Queue Pacing & Zombie Request Pruning

To protect your Bitrix24 portal from rate limit bans, OIA Shield24 utilizes single-threaded Durable Object queues. Each endpoint queue enforces a max queue depth of 40 requests and continuously monitors client connections. If a vendor client disconnects, Zombie Request Pruning (request.signal.aborted) flushes the pending job instantly.

• Queue full: request number 41 is refused at once with OIA_ERROR_PROXY_QUEUE_FULL (HTTP 503). Back off and retry; do not open more parallel connections.
• Per-endpoint RPM: over the endpoint's requests-per-minute allowance the gateway answers OIA_ERROR_RATE_LIMIT_EXCEEDED (HTTP 429) with a Retry-After header. Honour it.
• Pacing, not rejection: a request inside the allowance is never failed for being fast. It waits in the queue and is released at the paced rate. Your client sees a slower response, with the wait reported in the X-OIA-Queue-Time response header.
• Aborted clients: a request abandoned before it reaches the front of the queue is dropped without touching Bitrix24 (logged as HTTP 499, OIA_ERROR_CLIENT_CLOSED_REQUEST).

3. WAF & Payload Rules

Incoming payloads are evaluated against Zod schemas. Precision Payload Forcing executes deep JSON object merges (forced_payload) before dispatching to Bitrix24, overriding any unauthorized field modifications attempted by vendor callers.

• Shape of writes: *.add and *.update calls must send { "fields": { ... } } (optionally id and params). A few methods that take flat parameters, such as user.add, are exempt. Anything else must be a JSON object. Failures return OIA_ERROR_VALIDATION_FAILED or OIA_ERROR_INVALID_JSON (HTTP 400).
• Payload size: bodies over the endpoint's cap return OIA_ERROR_PAYLOAD_TOO_LARGE (HTTP 413). Nothing above 50 MB is accepted on any plan.
• HTTP verbs: each endpoint allows an admin-chosen set of verbs (default GET and POST). With "force POST for mutations" switched on, .add, .update, .delete, .set and batch over GET return HTTP 405.
• Network rules: optional IP allow and block lists (OIA_ERROR_FORBIDDEN_IP, HTTP 403) and an allowed-origins list for browser callers.
• Method names: must be lowercase, dot-separated Bitrix24 names. Encoded slashes, spaces or path tricks return OIA_ERROR_INVALID_METHOD before any rule is evaluated.

4. Subscription Plan Comparison

Over the monthly volume the gateway answers HTTP 429 (quota_exceeded). An unpaid or cancelled subscription answers HTTP 402 (OIA_ERROR_SUBSCRIPTION_INACTIVE).

5. Connecting to the Gateway

The gateway is a drop-in for the Bitrix24 REST URL. A developer, a script or an AI agent keeps the Bitrix24 method names, parameters and response shapes, and only swaps the base URL and the credential. Each endpoint is created by the portal administrator in the OIA Shield24 admin UI and runs in one of two modes.

An endpoint accepts only its own mode: sending a Bearer header to a webhook endpoint (or the reverse) returns OIA_ERROR_INVALID_CLIENT (HTTP 401). Keys can expire, be revoked, and be restricted to IPs; the gateway stores only a SHA-256 hash of the key.

Example calls

# API key mode
curl -X POST "https://oia-shield24.infinitybht.app/rest/crm.deal.list" \
  -H "Authorization: Bearer $OIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"STAGE_ID":"NEW"},"select":["ID","TITLE"]}'

# Webhook mode (the key is in the path)
curl "https://oia-shield24.infinitybht.app/rest/$ALIAS/$KEY/crm.deal.get?id=42"

# Write: fields must be wrapped
curl -X POST "https://oia-shield24.infinitybht.app/rest/crm.lead.add" \
  -H "Authorization: Bearer $OIA_KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Website lead"}}'

What the gateway does for you

• Credentials stay behind the gateway. The vendor never receives a Bitrix24 access or refresh token. The gateway injects and refreshes tokens itself, and the call runs as the endpoint's assigned portal user ("Run As User"). If that user has not authorized the app, calls fail closed (OIA_ERROR_ACCESS_USER_UNVERIFIED or OIA_ERROR_INVALID_GRANT) and never fall back to another user.
• Request formats: JSON bodies, form-encoded bodies and query strings, including Bitrix24's bracketed keys (filter[STAGE_ID]=NEW).
• REST 2 and REST 3.0: /rest/<method> reaches the classic API. /rest/api/<method> reaches REST 3.0 (for example note.*, main.eventlog.* and a few tasks.task.* methods) with the same policy and scope checks. REST 3.0 calls are sent to Bitrix24 as JSON POST.
• Batch (REST 2): POST /rest/batch with cmd works, up to 50 commands. Each command is run through the same method ledger, scopes, include and exclude lists and parameter guard as a direct call. One refused command refuses the whole batch with OIA_ERROR_BATCH_COMMAND_REFUSED (HTTP 403). The event methods cannot be called inside a batch.
• File downloads: Bitrix24 download links embed an access token, so the gateway rewrites them to /rest/.../oia.file.download?ref=.... The link is signed, valid for 24 hours, tied to the endpoint that received it, and still needs that endpoint's credential (GET only).
• Browser callers: CORS is answered per the endpoint's allowed-origins list.
• Response headers worth reading: X-OIA-Error-Code (the machine-readable code on a refusal), X-OIA-Queue-Time (milliseconds spent waiting), Retry-After.

6. Method Access Model

A call has to clear four independent layers. Failing any one of them stops the request before Bitrix24 sees it.

1. The Bitrix24 app scopes. OIA Shield24 can only call what the portal administrator granted to the app when installing it. Bitrix24 itself enforces this limit.
2. The OIA Shield24 methods ledger (mode: allowlist). A fixed, reviewed list of which methods can ever pass through the gateway, enforced for every tenant and every endpoint. A method the ledger blocks is refused even if the endpoint's scope is granted or the method is explicitly included. A method the ledger does not cover yet is refused too, until it has been reviewed and added.
3. The endpoint's scopes. The administrator grants each endpoint only the scope families it needs (for example crm and user_brief), derived from the first segment of the method, with exceptions such as voximplant.* mapping to telephony. Missing scope returns OIA_ERROR_INSUFFICIENT_SCOPE (HTTP 403).
4. The endpoint's method lists. Optional included-methods and excluded-methods lists narrow a scope further, for example read-only access to crm.*.list and crm.*.get.

Design principle: the gateway blocks only what would expose OIA Shield24 or its tokens. Everything else on the portal (CRM, tasks, deletes, custom fields, chats, telephony) is the portal administrator's decision. Concerns about risky-but-legitimate methods are shown to the administrator as advisories when they build the endpoint, not silently enforced.

7. Supported Methods

These scope families can be granted to an endpoint today. Within each family, individual methods can still be listed in the ledger as blocked (section 8).

The exact list, with the verification date and the reasoning for every decision, is the methods ledger shipped with the product. The admin UI lists the same data when you build an endpoint.

8. Methods That Are Never Supported

These calls are refused with OIA_ERROR_METHOD_BLOCKED (HTTP 403), whatever the endpoint is configured to allow. They are blocked for one of five reasons, each rooted in what the call would expose or break for every other tenant that shares the app.

Events: served by the gateway, not forwarded

event.bind, event.unbind, event.get, event.test and events would expose tokens if they were forwarded to Bitrix24, so the gateway never forwards them. With the event scope granted to the endpoint, OIA Shield24 answers them itself in the Bitrix24 response shapes. It binds its own webhook URL with Bitrix24 and relays each event to the vendor's handler, so the vendor never receives a Bitrix24 token.

• Approval first: by default a new subscription is accepted but delivers nothing until a portal administrator approves it in Outbound Events. The administrator can switch that off per endpoint.
• Handler rules: a public HTTPS URL of at most 2048 characters, not pointing at OIA Shield24 or at your Bitrix24 portal (OIA_ERROR_INVALID_HANDLER). At most 50 subscriptions per endpoint, each counted against the plan's outbound webhook limit.
• What arrives: Bitrix24's event body with every credential removed. auth[application_token] is the endpoint's own token, and the headers X-OIA-Event-Id, X-OIA-Timestamp, X-OIA-Signature (HMAC-SHA256, v1= prefix) and X-OIA-Signature-V2 (v2=, which also signs the event ID) let the vendor verify and de-duplicate. Delivery uses the retry queue and delivery log.
• Testing: event.test sends an ONAPPTEST event, signed like any other, to the calling endpoint's own ONAPPTEST subscriptions only. It is tried once and never retried, as in Bitrix24.
• Not available: offline events (event_type=offline returns ACCESS_DENIED) and event.offline.*. Subscriptions are checked against the endpoint's scopes before every delivery.

The full vendor guide is "Event Subscriptions for Vendors" in the in-app documentation.

Parameters that are refused on every method

Even on an allowed method, a request that contains any of these keys, at any depth in a JSON body, form or query string (case-insensitive), is refused with OIA_ERROR_FORBIDDEN_PARAMETER (HTTP 400). They stop a vendor from supplying its own Bitrix24 credentials or sneaking in a callback URL through a method the ledger has not classified.

auth, auth_id, refresh_id, access_token, refresh_token, application_token, client_secret, handler, callback, callback_url, placement_handler, event_handler, event_message_add, event_message_update, event_message_delete, event_welcome_message, event_bot_delete, event_command_add, webhookurl, iframe, action_uri, calculate_url, create_delivery_request_url, cancel_delivery_request_url, print_url, check_url

Ordinary custom fields such as UF_CRM_LEAD_HANDLER are not affected: the match is on the exact key.

Values that are removed from every response

Before a response or a relayed event reaches the vendor, the gateway strips auth_id, refresh_id, access_token, refresh_token, application_token and client_secret, and redacts any occurrence of the live access token in the body (for example inside a download URL). In event payloads, the auth block keeps domain, member_id, user_id, client_endpoint and scope, because handlers need them to tell portals and users apart. Neither grants access.

What this means in practice: an integration that must register placements, robots, bots, chat commands, payment or delivery handlers, or custom field types with Bitrix24 cannot do that through OIA Shield24 today. Install those pieces in the vendor's own Bitrix24 application, and use the gateway for the data calls. Event subscriptions are the exception (above).

9. Planned Support

These are gaps we know about and intend to close. They are direction, not dated commitments: until a capability is released, treat it as unsupported and do not build on it.

10. Error Reference

Every refusal is JSON of the form { "error": "OIA_ERROR_...", "error_description": "..." } and carries the same code in the X-OIA-Error-Code header. Errors that Bitrix24 itself returns (for example QUERY_LIMIT_EXCEEDED) pass through unchanged.

11. Notes for AI Agents and Automation

• Treat the endpoint credential as the whole identity. It cannot be widened by the client. Never ask a user for a Bitrix24 admin webhook or OAuth token; if the endpoint lacks a scope, report OIA_ERROR_INSUFFICIENT_SCOPE and ask the administrator.
• Read the code, not the prose. Branch on X-OIA-Error-Code. Retry only 429, 502, 503 and 504, with backoff (and Retry-After when present). OIA_ERROR_METHOD_BLOCKED, OIA_ERROR_INSUFFICIENT_SCOPE and OIA_ERROR_FORBIDDEN_PARAMETER never succeed on retry.
• Keep concurrency low. The queue serves one call at a time per endpoint at about 2 per second. Parallel calls only fill the 40-slot queue. Use REST 2 batch (up to 50 commands) for bulk reads and writes.
• Prefer least-privilege calls. Use select and filter to keep payloads small; plan caps apply per request body.
• Do not register URLs with Bitrix24 yourself. Placements, bots, robots and the other handler registrations are not available (sections 8 and 9). For events, call event.bind on the gateway as usual, then wait for the administrator to approve the subscription, and verify each delivery with the signature header.
• Links in responses. Use the gateway download links exactly as returned; they expire after 24 hours and need the same credential.

See also the articles and llms.txt for step-by-step guides.