Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.proof.community/llms.txt

Use this file to discover all available pages before exploring further.

All Proof API errors return a JSON body of the shape: 
{
  "error": "<slug>",
  "code": "<code>",
  "message": "<human-readable description>"
}
The HTTP status code, the error slug, and the code together identify the failure mode. Use them together for programmatic handling; use message for logs only. The X-Request-Id response header carries a request identifier; include it in any support ticket.

​
Error matrix

HTTPerrorExample code valuesCauseAction
400invalid_requestvalidation_error, decode_error, missing_param, currency_not_allowedBad request body, missing field, or currency not enabled for your integrationFix the request
400wallet_not_supportedWALLET_NOT_SUPPORTEDNo active wallet for the requested (currency, network)Ask Proof to provision the wallet
401unauthorisedmissing_token, invalid_tokenAuthorization missing or client_token unknown/inactiveCheck the header value; rotate token if compromised
403forbiddenforbidden_originRequest IP or Origin not on your allowlistVerify your server IP is registered with Proof
404not_foundnot_foundTransaction, user, or wallet does not exist or does not belong to your partnerVerify the identifier
500internal_errordb_error, token_errorProxy-side faultRetry once; contact support if it persists
500publish_failedkafka_unavailableProof failed to publish a lifecycle event (webhook path only)Retry your webhook delivery; Proof will redeliver
502upstream_errorprovider_errorAn external service returned an errorRetry with the same body
502upstream_unavailableupstream_unavailable, upstream_invalid_responseAn external service is unreachable or returned an unparseable bodyRetry; back off if it persists

​
Common scenarios

​
currency_not_allowed (400)

The currency field of your session request is not one of the currencies enabled for your integration. 
{
  "error": "invalid_request",
  "code": "currency_not_allowed",
  "message": "currency=BTC"
}
Ask the Proof team to add the currency, or pick one already on your list.

​
wallet_not_supported (400)

You requested a (currency, network) pair for which Proof has no active wallet for your partner. 
{
  "error": "wallet_not_supported",
  "code": "WALLET_NOT_SUPPORTED",
  "message": "no active wallet for currency=USDT network=BEP20"
}
Either request a network for which Proof has a wallet (e.g. TRC20), or ask the Proof team to provision a wallet for the desired pair.

​
forbidden_origin (403)

The request came from an IP address not on your partner record’s allowlist.
  • Confirm the IP address your backend server makes outbound requests from.
  • Ask the Proof team what IP is on file for your partner, or to add a new IP.
  • When adding a new server or moving to a new cloud region, register the IP before the traffic starts.

​
upstream_error (502)

An external service returned an error. The proxy does not retry automatically for POST /widget/session — your client should. 
async function createSessionWithRetry(body, attempt = 0) {
  const res = await fetch("https://DOMAIN/widget/session", {
    method: "POST",
    headers: { Authorization: "Bearer <client_token>", "Content-Type": "application/json" },
    body: JSON.stringify(body)
  });
  if (res.status === 502 && attempt < 2) {
    await new Promise(r => setTimeout(r, 500 * (attempt + 1)));
    return createSessionWithRetry(body, attempt + 1);
  }
  return res.json();
}

​
Widget-level errors

The widget’s onStatusChange callback also fires for payment-side failures (e.g. card declined, 3DS failure). These are informational — the authoritative status comes from the API. See Transaction Status.