Error codes

API V2#

A V2 error has the shape { "message", "code" } (plus errors for a validation). The message is in French and may change: base your logic on the code, and accept an unknown code.

{
  "message": "Solde insuffisant : 1200.00 CDF disponibles, 5175.00 CDF demandés.",
  "code": "INSUFFICIENT_BALANCE"
}

• Payment refused by the provider: 422 response with the payment in data (status: "failed"); the reason is in data.failure.code and data.failure.message, passed on from LabPay.
• Rate limit (429): { "message": "Too Many Attempts." } response without code, with the Retry-After header.
• Invalid filters on GET /V2/providers, GET /V2/availability and GET /V2/notifications: 422 { "message", "errors" }, without code.

Suspended features (503)#

From its console, LabPay can suspend an API version or an operation (maintenance, provider incident…). The request is then refused before any processing: nothing is created or debited. The 503 response carries the code and, for console switches, the feature field (feature concerned); message gives the reason entered, if any.

{
  "message": "Les remboursements sont momentanément désactivés.",
  "code": "FEATURE_DISABLED",
  "feature": "operations.refunds"
}

• A switch applies within about thirty seconds. Notifications (webhooks) are never cut, and reads only are when the whole version is.
• Do not retry in a loop: wait, or offer another payment method. The SDKs only retry these refusals after a Retry-After header.
• The live status (open versions and operations, reasons) is shown on the documentation home page.

With the SDKs#

The SDKs raise an error typed by code (then by HTTP status); a payment refused at initiation (422 with the payment) is returned with status: failed, not raised. Codes newer than the SDK (e.g. API_VERSION_DISABLED, FEATURE_DISABLED) arrive with the class of their status (503 → service unavailable), code intact. Full mapping on each SDK page.

<?php
use Labyrinthe\LabPay\Client;
use Labyrinthe\LabPay\Exception\ApiException;
use Labyrinthe\LabPay\Exception\ConnectionException;
use Labyrinthe\LabPay\Exception\ServiceUnavailableException;
use Labyrinthe\LabPay\Exception\ValidationException;

$labpay = new Client('test_xxxxxxxxxxxxxxxx'); // ou Client::fromEnv() (LABPAY_API_KEY)

try {
    $payment = $labpay->deposits->create(amount: '1000', currency: 'CDF', phone: '0813456789', reference: 'ORDER-42');
    if ($payment->isFailed()) {
        // refusé dès l'initiation (422 avec le paiement) : renvoyé, pas levé
        echo $payment->failure->code;
    }
} catch (ValidationException $e) {
    $e->getErrors();                 // messages par champ
} catch (ServiceUnavailableException $e) {
    $e->getErrorCode();              // MAINTENANCE, DEPOSITS_DISABLED… ; $e->getRetryAfter()
} catch (ConnectionException $e) {
    // PAS un échec : renvoyer la même référence ou payments->findByReference('ORDER-42')
} catch (ApiException $e) {
    $e->getErrorCode();              // toujours le code, jamais le message
}

API V1 (legacy)#

V1 has no code field: an error has success: false, a readable message, results.status (status from the table below) and errors (list) for a validation. The table gives the response name and its HTTP status.

Suspended features (V1)#

A suspended version or operation also answers 503 in V1, in the usual envelope (success: false, message…) with code and feature added: API_VERSION_DISABLED (api.v1), DEPOSITS_DISABLED (payment/mobile), WITHDRAWALS_DISABLED (payment/withdrawal), FEATURE_DISABLED (payment/inter-transfer).