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 takes care of delivering 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.

Parameters

A platform key vibe_… is not accepted on this route.

Request fields (body)

The body is JSON with one of two outcomes. The body is limited 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 vcr_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 is present only when the size limit is exceeded. A 409 SOLUTION_CALL_CLOSED carries the error.state field instead — the call state.

Errors

Full list of common API errors — Errors.

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 reply headers exist only on a contract call. When a business process action calls the solution through the application external API, X-Vibe-Reply-Url, X-Vibe-Reply-Token and X-Vibe-Reply-Deadline do not arrive. There the action sends the X-Bitrix24-Event-Token header, and the solution sends the result as a process event through POST /v1/workflows/event. The {$request.header.X-Vibe-Reply-Url} expression in the contract's callbacks.result refers to a header on this path. The result schema under it is shared by both channels: on the external API channel, returnValues is built from it. For the requirements for the key that sends the process event and a ready-made handler, see A long-running method in a business process.

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. Any other response (5xx, 3xx, 2xx other than 200 and 202), a dropped connection or a timeout is treated by the platform as a transient failure. It retries the delivery at increasing intervals 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 unconditionally.

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 in 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
• A long-running method in a business process
• What the app receives
• Application catalog
• Errors