#API Conventions

Status: Available. The general rules that are the same for all endpoints of the server API.

Purpose: request and response format, errors and the full code catalog, pagination, idempotency, asynchronous operations, rate limits, versioning, and paid operations.

The JSON examples below are illustrative: the names of optional fields will be refined in the OpenAPI 3.1 specification.

#Contents

1. Request and response format
2. Errors
3. Error code catalog
4. Pagination
5. Idempotency
6. Asynchronous operations
7. Rate limits
8. Versioning
9. Paid operations
10. Wallet and exchange suspension

#Request and response format

#Response headers

#Request headers

#Errors

All errors are application/problem+json per RFC 9457. The error text contains no stack traces and no database details.

#Fields

An errors[] element:

#Example

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-Id: req_EXAMPLE0003

{
  "type": "https://formula-cream.pro/developers/errors#validation_failed",
  "title": "Запрос не прошёл проверку",
  "status": 422,
  "code": "validation_failed",
  "detail": "Один или несколько параметров некорректны.",
  "request_id": "req_EXAMPLE0003",
  "errors": [
    { "field": "/limit", "code": "out_of_range", "message": "Должно быть от 1 до 100." }
  ]
}

#How to handle them

#Error code catalog

The HTTP statuses of the codes are fixed. The description of each code is available at the address in the type field: https://<cell domain>/developers/errors#<code>.

#Authentication and access

#Request and resource state

#Money and limits

#Platform

#Not errors: reasons the AI did not reply

These values arrive in the body of a successful response, not as an error. Ingesting the customer message succeeded; the AI seller did not reply, for the stated reason. The state of the AI reply is carried by the ai_reply field in the response to a customer message and in the message.created event; for details, see the Conversations server API.

ai_reply is an object {status, reason?}:

Do not treat these values as a failure: the message was accepted and saved. In the widget's client Chat API, the same daily_limit case is reported with the queued: true field (client Chat API).

#Pagination

Lists are returned with a cursor ("keyset"), not page numbers.

GET /api/public/v1/leads?limit=50&cursor=eyJ2IjoxLC4uLn0 HTTP/1.1

Response:

{
  "data": [
    { "id": "lead_EXAMPLE01", "status": "new", "updated_at": "2026-10-11T08:15:30Z" }
  ],
  "next_cursor": "eyJ2IjoxLC4uLn0"
}

When next_cursor is null, the list has ended.

#Cursor properties

#What happens when data changes during a traversal

• Added records will appear in the traversal if they land "after" the current position.
• A modified record gets a new updated_at and therefore may appear again later. Process records as "upsert by id", not "insert".
• Deleted records are not returned by default. With include_deleted=true, "tombstones" arrive in their place: objects {"id": "…", "deleted_at": "2026-10-11T08:15:30Z"}, so you can remove the record on your side. Tombstones are retained for 30 days: sync at least that often.
• Records are not skipped because of changes in neighboring rows.

For real-time synchronization, use webhooks, and leave periodic traversal for reconciliation.

#Idempotency

The Idempotency-Key header protects against duplicates when retrying after network failures and timeouts.

Behavior on a retry with the same key:

Recommendations:

• Generate the key before the first send and store it with the task in your queue, so a retry uses the same key.
• For 429 and 5xx, retry the request with the same key.
• Do not use one key for different operations.

The platform does not store personal data in idempotency records: a retry redraws the response from the resource's current data.

#Asynchronous operations

Long operations (an AI seller reply, article generation, a strategist turn) do not hold the connection open. They follow a single scheme: the request returns 202 Accepted with an operation object; you can wait for the result, poll for it, or receive it as an event.

POST …  (Idempotency-Key)            →  202 Accepted  +  {"operation": {…}}
                                            │
         ┌──────────────────────────────────┼──────────────────────────────┐
         ▼                                  ▼                              ▼
   ?wait=N (up to 20 s):             polling                        webhook event
   wait for the same job             GET /operations/{id}           operation.completed
                                                                    (and the module's event)

#The operation envelope

The same object is returned from the creating request, from GET /operations/{id}, and in the operation.completed event.

202 example:

{
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "queued",
    "created_at": "2026-10-11T08:15:30Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" }
  }
}

Kinds of operations:

Lead scoring (POST /leads/{id}/score) runs synchronously and is not wrapped in the envelope.

#Ways to get the result

#GET /operations/{id}

Returns an operation of your integration. It requires no separate scope: to read the result, you need the scopes of the resource itself (for example, conversations:read). An operation of another integration or another tenant is returned as 404 not_found.

200 response:

{
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "succeeded",
    "created_at": "2026-10-11T08:15:30Z",
    "completed_at": "2026-10-11T08:15:41Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" },
    "usage": { "cost": { "amount": "0.42", "currency": "RUB" }, "model": "model-EXAMPLE" }
  }
}

Properties:

• The job is recovered after a worker failure; the reserve of paid funds is returned if the operation did not complete.
• Repeating the request with the same Idempotency-Key returns the same operation.
• The result of a paid operation contains usage (see below).

#Rate limits

Limits are counted with a sliding window per key and per tenant at the same time.

The values are starting values and may change; limits by plan are not fixed. The actual values for your key are visible in GET /me (limits). Ingesting events and offline conversions (analytics:write) counts as a write: 120 requests per minute, at most 100 events per batch.

#Headers

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

#Limits store failure

• For writes and paid operations the mode is "fail closed": when the limits store is unavailable, 503 service_unavailable is returned (with Retry-After). The platform will not allow uncontrolled spending.
• For reads, a soft in-process limit applies, and requests continue to be served.

#Recommendations

• Read RateLimit-Remaining and slow down in advance.
• Retry 429 after Retry-After with jitter, not as an avalanche.
• For bulk synchronization, use cursor traversal and webhooks instead of frequent polling.

#Versioning

• The version is part of the address: /api/public/v1.
• Within v1, only additive changes are made: new endpoints, new optional parameters, new response fields, and new enum values where stated. The client must ignore unknown fields.
• A breaking change ships only in a new version (v2) and never replaces v1.
• Deprecation is announced in advance: Deprecation and Sunset headers in responses and an entry in the changelog, at least 90 days before shutdown.

#Paid operations

Paid operations charge money to the tenant's wallet: an AI seller reply, lead scoring, article generation, a strategist turn. They are assigned to separate scopes (Authentication).

#Protection against uncontrolled spending

When the wallet state is unknown (the balance source did not respond), paid operations are closed: 503 upstream_unavailable with Retry-After. Free reads keep working and carry the header Sapport-Wallet-State: unknown.

The limit values are configured in the tenant dashboard; the effective values for concurrency and daily spend are visible in GET /me (limits.paid_concurrency, wallet.daily_spend).

#Responses

#Cost in the response

Every successful response of a paid operation, as well as the operation envelope of a paid operation, contains a usage field:

Example (illustrative): lead scoring, a synchronous paid operation:

{
  "lead_id": "lead_EXAMPLE01",
  "score": 72,
  "usage": {
    "cost": { "amount": "0.12", "currency": "RUB" },
    "model": "model-EXAMPLE"
  }
}

Test keys do not charge money (Authentication).

#Cheat sheet

#Wallet and exchange suspension

If the tenant wallet balance is below zero or the wallet is blocked, data exchange halts entirely: every route except GET /me and GET /wallet responds with 402 wallet_suspended before scopes are checked and before the request body is read, and outgoing webhooks are not sent but deferred. The response carries topup_url (where to top up) and balance (the balance at the moment of refusal). The state is always visible in GET /wallet and in the wallet block of the GET /me response. The full description, states, and examples are in Wallet and exchange suspension.