HTTP errors

The error envelope, what each status code means, and how to decide whether a request can be retried. Codes specific to one operation are on that operation's page.

This section lists error codes returned by the LB Pay iGaming API and related webhook management routes. Errors are grouped by HTTP status code.

Use the type or errorCode field in the JSON body to branch in your integration. See the API Reference for per-route details.

What to do, by status code

Before looking up a specific code, decide whether the request is safe to retry. Retrying the wrong class of error either wastes time or duplicates money.

HTTP	Meaning	Action
400	Validation error	Fix the payload. Do not retry automatically — the same request fails identically.
401	Token invalid or expired	Renew the token and retry once.
403	Forbidden	Check account configuration. Do not retry automatically.
404	Resource does not exist	For withdrawals: invalid PIX key or account. Notify the player.
422	Business rule violated	Definitive. Never retry. Branch on errorCode and inform the player.
500	Internal error	Confirmed failure. The transaction was rejected. Close it as failed.
502 / 503	Upstream or timeout	Outcome unknown. Query via GET before retrying. Never assume failure.

A timeout is not a failure

503 and network timeouts mean no answer, not no transaction. LB Pay may have processed the request. Always confirm with a GET using the same externalId before retrying or rolling anything back — see Retries and timeouts.

Response format

iGaming API

{
  "type": "InvalidParameter",
  "title": "Bad Request",
  "status": 400,
  "detail": "Parameter 'externalId' must be a valid UUID",
  "timestamp": "2026-04-07T12:00:00Z",
  "path": "/v1/pix/withdraw/pix-key",
  "errorCode": "IGAMING_CPF_MISMATCH",
  "retryable": false,
  "violations": [
    {
      "reason": "must be a valid UUID",
      "property": "externalId",
      "value": "invalid"
    }
  ]
}

Field	Description
type	Error category (e.g. InvalidParameter, NotFound)
errorCode	Business code on 422 responses; use for deterministic branching
retryable	false when retrying the same request will not succeed
violations	Validation details for malformed input

Webhook management

{
  "code": "invalid_event",
  "message": "One or more subscribed events are invalid"
}

Common errors

These codes can appear on multiple routes.

BAD_REQUEST (400)

Error code	Description
InvalidContentType	Request Content-Type is not application/json.
MalformedRequest	Empty body or DTO validation failed.
InvalidJSON	Request body is not valid JSON.
MissingParameter	A required path or query parameter is missing.
InvalidParameter	A path, query, or body parameter has an invalid value (e.g. externalId is not a UUID).
INVALID_DATE_RANGE	Statement date range is invalid, incomplete, in the future, or exceeds 90 days.
MISSING_REQUIRED_FILTER	Statement query requires a date range or an endToEndId / productTransactionId filter.
INVALID_PAGE_SIZE	Statement pageSize must be between 1 and 100.
INVALID_QUERY_PARAMETER	Statement query parameter is invalid or unparsable (e.g. productTransactionId is not a UUID).

UNAUTHORIZED (401)

Error code	Description
Unauthorized	Missing or invalid Bearer token, or account context could not be resolved.

FORBIDDEN (403)

Error code	Description
Forbidden	The authenticated client does not have permission to perform this action.

NOT_FOUND (404)

Error code	Description
NotFound	The requested resource was not found (withdrawal, deposit, refund, transfer, or account).
PIX_KEY_NOT_FOUND	The Pix key used for withdraw does not exist.
ACCOUNT_NOT_FOUND	The account referenced in the request was not found.

UNPROCESSABLE_ENTITY (422)

Error code	Description
IGAMING_CPF_MISMATCH	Pix key holder CPF does not match the account tax_id.
SECURE_LOOP_ACCOUNT_MISMATCH	Secure Loop verification failed for the expected payer or creditor.
ACCOUNT_MISMATCH	Creditor account data does not match the settled payment (withdraw GET).

INTERNAL_SERVER_ERROR (500)

Error code	Description
InternalError	An unexpected error occurred while processing the request.
INTERNAL_SERVER_ERROR	Failed to retrieve statement or balance data.

BAD_GATEWAY (502)

Error code	Description
INTERNAL_SERVER_ERROR	Upstream ledger service returned an error.

SERVICE_UNAVAILABLE (503)

Error code	Description
ServiceNotAvailable	A downstream service (processor or ledger) timed out or is temporarily unavailable.

Seamless Pix (BACEN-aligned)

Routes under /v1/cob, /v1/pix/payments, and legacy Seamless paths use BACEN-style error types in the type field:

BAD_REQUEST (400)

Error code	Description
RequisicaoInvalida	Invalid request schema.
ChaveInvalida	Invalid Pix key.
ValorInvalido	Invalid amount.

FORBIDDEN (403)

Error code	Description
AcessoNegado	Authorization denied.

NOT_FOUND (404)

Error code	Description
NaoEncontrado	Resource not found.

SERVICE_UNAVAILABLE (503)

Error code	Description
ServicoIndisponivel	Service temporarily unavailable.

Full route list: API Reference.