Deliver the result of a long-running method

POST /v1/solution-calls/:callId/result

Accepts the outcome of a long-running contract method call from the solution and itself delivers it to the Bitrix24 account. The solution receives the address of this route, a single-use reply token and the deadline as headers on the call itself, so it needs neither a platform key nor any extra setup.

How a long-running call arrives

The platform invokes a contract method with x-vibe-async: true the same way as a regular one: an HTTP request to the solution's route from the contract, through the application tunnel. Five headers set a long-running call apart:

The common contract-call headers arrive here as well: X-Vibe-Request-Id, X-Vibe-Caller-Kind with the value contract, X-Vibe-Caller-Portal-Id, X-Vibe-Portal-User-Id, X-Vibe-Operation-Id, X-Vibe-Contract-Version and Idempotency-Key. The X-Vibe-Invocation-Context header is present only on a call that was made with a context. A contract call carries no X-Vibe-Caller-Key-Id or X-Vibe-Caller-App-Id — it does not go through an external API key.

The solution can answer such a call in two ways:

A 4xx response closes the call as failed without a result — sending one later is pointless. Every other response — 5xx, 3xx, 2xx other than 200 and 202 — together with a dropped connection and a timeout the platform treats as a transient failure and retries the delivery with growing pauses until the deadline from X-Vibe-Reply-Deadline — with the same X-Vibe-Call-Id and the same reply token, so this route accepts a result computed on the first attempt without reservations.

Parameters

Authentication is the Authorization: Bearer header with the reply token from X-Vibe-Reply-Token of the same call. A platform key vibe_… is not accepted on this route, and the reply token opens no other address.

Request fields (body)

The body is JSON with one of two outcomes. The body size is up to 512 KiB, measured in raw bytes before parsing.

Body with failed:

{
  "outcome": "failed",
  "error": {
    "code": "INVOICE_LOCKED",
    "message": "Invoice is locked by another user",
    "problem": {
      "type": "https://example.com/problems/invoice-locked",
      "title": "Invoice locked",
      "detail": "Invoice 17 is being edited",
      "instance": "/invoices/17"
    }
  }
}

Examples

The route has a single authorization axis — the reply token from X-Vibe-Reply-Token, so there is one example per language: a personal key and an application authorization key get 401 REPLY_TOKEN_INVALID.

curl — reply token

curl -X POST "https://vibecode.bitrix24.com/v1/solution-calls/call_01M31PGZ80V9GJMWJ5N48AATB2/result" \
  -H "Authorization: Bearer YOUR_REPLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "completed", "result": {"invoiceNumber": "A-17"}}'

JavaScript — reply token

// Headers of the incoming call — from the long-running method handler in the solution.
const replyUrl = req.headers['x-vibe-reply-url'];
const replyToken = req.headers['x-vibe-reply-token'];

const res = await fetch(replyUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${replyToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ outcome: 'completed', result: { invoiceNumber: 'A-17' } }),
});

const body = await res.json();
if (!body.success) {
  // A 4xx closes the call: retrying the same result is pointless.
  console.error(`result not accepted: ${body.error.code}`);
}

Response fields

Response example

{
  "success": true,
  "data": {
    "state": "completed"
  }
}

Error response example

422 — the body is over 512 KiB, the call is closed as failed:

{
  "success": false,
  "error": {
    "code": "RESULT_INVALID",
    "message": "The result body is over the boundary-contract limit; the call is closed as failed",
    "errorCode": "SOLUTION_RESULT_TOO_LARGE",
    "limitBytes": 524288
  }
}

The error.errorCode field names the reason — SOLUTION_RESULT_TOO_LARGE or SOLUTION_BAD_RESPONSE — and the outcome reaches the Bitrix24 account with the same code. The error.limitBytes field comes only when the size is exceeded. A 409 SOLUTION_CALL_CLOSED carries the error.state field instead — the call state.

Errors

Full list of common API errors — Errors.

Known specifics

• Any 4xx closes the call for good. A 422 is not an invitation to fix the body and retry: the call has already moved to failed, the outcome with the reason code has gone to the Bitrix24 account, and the same token answers 409 from then on. Validate result against the callbacks.result schema before sending — a fix in the solution's code helps the next call, not this one.
• Retry only after a 5xx or a dropped connection. The token is single-use per accepted outcome, not per attempt: until the platform has answered 2xx or 4xx, the result is not recorded, and a retry with the same address, token and body is mandatory — otherwise the step on the Bitrix24 account waits out the deadline and ends with a timeout. An unfinished attempt holds the call for one to two minutes, and during that time the answer is 409 with state: accepted.
• The reply token is the secret of one call. Whoever holds it can close your call with any result. Do not write it to a log, do not show it in the interface and do not pass it on. The platform writes neither the token nor the result body to its own logs.
• After the deadline or a cancellation the Bitrix24 account no longer needs the result. A 409 with state: expired or state: canceled is the signal to stop the long-running work: there is no point continuing it, and there is nowhere left to accept its outcome.
• A 200 means "the outcome is recorded", not "the Bitrix24 account has received it". The platform handles the delivery to the Bitrix24 account itself, with retries while the account is unavailable. The solution does not need to do anything for that.

See also

• Application external API
• What the app receives
• Application catalog
• Errors