Errors & outcomes

Three things can go wrong and they are kept apart on purpose: a thrown error means the SDK is unusable as configured; an outcome records what happened to one request; an API error code comes back from the service. Every one of them is listed here with its corrective action.

Typed errors — PHP

All three extend \RuntimeException, so one catch (\Legibl\Exception\LegiblException $e) clause catches everything the SDK raises and nothing else.

Legibl\Exception\ConfigurationException

The SDK is not usable as configured. Raised at first use rather than at some arbitrary later point, and the message always names the fix. There are four sites that raise it.

Unknown Legibl mode "…". Expected one of: live, stub, replay, dry_run.

Fix: LEGIBL_MODE holds a value outside that set — often a typo or a shell variable that expanded to empty plus something else. Set it to one of the four, or unset it and let the mode be inferred.

Legibl is in live mode but no API key is set. Set the LEGIBL_API_KEY environment variable, or use stub mode for local development.

Fix: you forced LEGIBL_MODE=live without LEGIBL_API_KEY. Set the key, or drop the explicit mode so the SDK falls back to stub. Common in containers where the key is injected into the app but not into a worker or cron process.

Legibl is in replay mode but no fixture corpus is configured. Set the LEGIBL_FIXTURES environment variable to the corpus directory.

Fix: point LEGIBL_FIXTURES at the corpus directory, or stop forcing LEGIBL_MODE=replay.

HttpSolver requires an API key. Set LEGIBL_API_KEY, or use stub mode.

Fix: you constructed HttpSolver directly with a Config that carries no key. Build the interceptor through Interceptor::fromConfig() instead, which selects a solver the mode actually supports.

Legibl\Exception\LegiblException

The base class, and raised directly in exactly one place: Legibl\curl_multi_exec().

Legibl does not wrap the curl multi-handle API, so challenge handling would be
silently inactive for these requests. Use the global \curl_multi_exec()
explicitly to acknowledge that, or route these requests through Legibl\curl_exec().

Fix: either call \curl_multi_exec() by its qualified global name — which acknowledges that those requests get no challenge handling — or move them onto Legibl\curl_exec(). The function refuses rather than forwarding silently, because a silent forward leaves the SDK looking installed while every challenge on those requests passes unhandled.

Legibl\Exception\SolveFailedException

Typed errors — Python

All three subclass RuntimeError, so except legibl.errors.LegiblError catches everything the SDK raises.

Outcomes

Every intercepted request produces exactly one outcome, delivered to your observer with the target domain and the elapsed time. These are the errors most customers will actually see, because the SDK's governing rule is graceful degradation: it returns your original response rather than raising.

Exact reason strings

The reason field is prose intended for a human reading a log. These are the strings this version emits.

Solve-failure messages

When a solve does not happen, the solver calls solveFailed / solve_failed on your observer with one of four messages, suffixed with the service's errorCode when the response carried one.

Service error codes

The full errorId / errorCode envelope and its code table are on the HTTP API page.