Errors

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.

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"
}

Error index

Browse errors by domain:

Topic	Description
Pix In	Deposit / immediate charge
Pix Out	Withdraw by Pix key or manual
Pix Refund	Refund operations
Internal transfer	Account-to-account transfer
Balance	Realtime and closing-day balance
Statement	Detailed and consolidated statement
Webhooks	Webhook configuration and delivery

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.