Errors, retries, and payment headers

Payment headers

PAYMENT-REQUIRED comes with an HTTP 402 payment request. Copy it unchanged to the payer. PAYMENT-RESPONSE comes after payment succeeds. It is payment proof that the SDK checks before it returns the paid result.

Keep each payment-header value exactly as you received it.

PAYMENT-RESPONSE is encoded JSON. The SDK validates and attaches it for you. A direct HTTP integration returns the exact value from Recuut’s successful completion response. Merchants must never construct, re-encode, or edit this payment proof.

SDK errors

Import generic SDK errors from recuut. Import generated Merchant response errors and enums from recuut.merchant_api. For a known Merchant API error, read code and message.

Advanced error details

Raw content bytes and headers remain available when you need to return a payment request exactly or inspect logs. A future status, undocumented error code, or malformed payload raises RecuutUnexpectedResponseError with the original status, body, and headers.

import osfrom recuut import Recuutfrom recuut.merchant_api import (    AccessRequest,    AccessResource,    PaymentRequiredError,    SettlementAsset,)def relay_challenge(    *, body: bytes, payment_required: str) -> tuple[bytes, dict[str, str]]:    return body, {"PAYMENT-REQUIRED": payment_required}try:    with Recuut() as client:        client.payments.access(            access_request=AccessRequest(                revision_id=os.environ["RECUUT_REVISION_ID"],                settlement_asset=SettlementAsset.USDC,                resource=AccessResource(                    url="https://merchant.example/reports/quarterly",                    description="Quarterly report",                    mime_type="application/json",                ),            )        )except PaymentRequiredError as error:    if error.payment_required is not None:        response_body, response_headers = relay_challenge(            body=error.content,            payment_required=error.payment_required,        )    else:        print(error.status_code, error.code, error.message)        print(error.header("Retry-After"))

Retry discipline

Do not retry every failure automatically. When Recuut says payment is required, return its 402 response to the payer unchanged. If Retry-After is present, wait that long. For a temporary network or server error, retry a limited number of times with increasing waits.

Keep the paid result private until completion succeeds. A network interruption can cause a retry. Make important side effects safe to run more than once when possible. A successful transaction and receipt are the saved payment record. An app timeout alone does not prove payment failed.

Use payment_request_id to match a transaction to the original attempt in your logs. Do not derive payment status from that ID.

Inspect exact responses and schemas → · OpenAPI JSON →