bitrix-result-and-errors

Result and Error

Baseline: main 23.0+ · Verified: main 26.800.0

Contract

• Expected failures (validation, business rule, not found, no rights) → Result with Errors.
• Broken state or contract (module missing, DB down, misconfiguration, bug) → exception.
• One method, one contract: always a Result, or a value plus exceptions for the exceptional case. Never bool/null/-1/['error' => …].

Bitrix\Main\Result

use Bitrix\Main\Error;
use Bitrix\Main\Result;

$result = new Result();
if ($title === '')
{
    return $result->addError(new Error('Title required', 'BLOG_POST_TITLE_EMPTY', ['field' => 'title']));
}

return $result->setData(['id' => $id]);

• isSuccess(), addError(Error), addErrors(Error[]), getErrors(), getError() (first or null), getErrorMessages(), getErrorCollection(), setData(array), getData(). Setters return $this.
• setData() silently drops SqlExpression values.

Error and codes

new Error($message, $code = 0, $customData = null). JSON form: {"message", "code", "customData"}.

• Codes are stable and machine-readable: module + entity + reason (BLOG_POST_NOT_FOUND), kept in constants. Clients branch on the code, not the text.
• Messages via Loc::getMessage('BLOG_ERROR_POST_TITLE_EMPTY').
• ErrorCollection: new ErrorCollection([$error]), setError(), add([...]), getErrorByCode('CODE'), iterable, isEmpty(), toArray().

Typed result

Give callers getters instead of getData()['post']:

final class CreatePostResult extends \Bitrix\Main\Result
{
    private ?Post $post = null;

    public function setPost(Post $post): self
    {
        $this->post = $post;
        return $this;
    }

    public function getPost(): ?Post
    {
        return $this->post;
    }
}

ORM results (Bitrix\Main\ORM\Data\*)

• AddResult: getId(), getPrimary(), getObject().
• UpdateResult: getId(), getPrimary(), getAffectedRowsCount().
• DeleteResult: no methods of its own (no affected-rows count).
• Bitrix\Main\Entity\*Result are compat aliases. Write ORM\Data\*.
• A failed ORM result whose errors nobody read (isSuccess() / getErrors()) raises E_USER_WARNING on destruct. Always check it and return it, or copy its errors up.

$add = PostTable::add(['TITLE' => $title]);
if (!$add->isSuccess())
{
    return (new Result())->addErrors($add->getErrors());
}
$id = $add->getId();

Other result types

• EventResult (SUCCESS, ERROR, UNDEFINED) is a handler's answer, not a service result: bitrix-events.
• ValidationResult (bitrix-validation) extends Result: add its errors to the service result.

Controllers

$this->addErrors($result->getErrors()); return null; gives {"status":"error","data":null,"errors":[…]}. Envelope details: bitrix-controllers.

Exceptions at the boundary

Catch at the module/controller edge, log, return a generic error:

try
{
    return $this->service->run($dto);
}
catch (\Bitrix\Main\SystemException $e)
{
    $this->logger->error('Run failed', ['exception' => $e]);
    return (new Result())->addError(new Error('Internal error', 'VENDOR_INTERNAL_ERROR'));
}

• Never swallow \Throwable without logging.
• Developer mistakes (InvalidArgumentException, LogicException, TypeError) and "can't happen" domain states (division by zero in a money type) stay exceptions.