Toda resposta de erro tem o mesmo corpo. Decida pelo errorCode, nunca pelo
message — o texto é apresentação e pode mudar; o código é contrato.
{"errorCode": "insufficient_funds","message": "Saldo insuficiente para concluir a operação.","docs": "https://docs.api.corpx.com/baas/guias/referencia/erros#insufficient_funds","requestId": "3f7c2a9e-1b4d-4c8e-9f0a-2b6d7e8f9a0b","partner": { "code": "INSUFFICIENT_BALANCE", "message": "Saldo insuficiente" }}
| Campo | O que é |
|---|---|
errorCode | Código estável. A lista abaixo é gerada do código-fonte do gateway a cada release. |
message | Explicação em português, para log e suporte. Não faça parsing. |
docs | Link para a âncora do código nesta página. |
requestId | Id da requisição no gateway. Cite ao abrir chamado. |
partner | Só quando a falha veio do liquidante: o erro cru dele, para diagnóstico. |
Novos códigos podem surgir sem mudança de versão. Trate um errorCode
desconhecido como erro genérico do mesmo status HTTP: 4xx é problema na
requisição (não repita sem mudar algo), 5xx e retryable: sim podem ser
repetidos com a mesma Idempotency-Key.
Gerais
Autenticação, headers, formato e disponibilidade. Podem acontecer em qualquer rota.
| Código | HTTP | O que aconteceu e o que fazer | Retentativa |
|---|---|---|---|
account_blocked | 423 | A conta foi bloqueada operacionalmente pela CorpX. Consultas e entradas continuam disponíveis, mas saídas financeiras são recusadas até o desbloqueio. | não |
account_has_balance | 422 | POST /v1/accounts/{accountId}/close no caminho exclusivo: o liquidante ainda tem saldo disponível (available ≠ 0, ou total ≠ 0 sem bloqueio). Retire o saldo antes. O corpo traz o saldo cru do liquidante. | não |
account_has_locked_balance | 422 | POST /v1/accounts/{accountId}/close no caminho exclusivo: o saldo disponível está zerado, mas há saldo bloqueado no liquidante (locked ≠ 0, por exemplo retenção de MED). A conta só é encerrada depois que o bloqueio é liberado. O corpo traz o saldo cru do liquidante. | não |
account_has_pix_keys | 422 | POST /v1/accounts/{accountId}/close no caminho exclusivo: a conta ainda tem chave PIX no liquidante. Exclua as chaves antes. O corpo traz só o tipo de cada chave, não o valor. | não |
account_holder_missing | 404 | O liquidante não devolveu o cadastro do titular desta conta. | não |
account_not_found | 404 | O accountId do path não existe. | não |
acting_not_holder | 403 | X-Acting-Document não é o documento do titular da conta. | não |
bank_not_found | 404 | GET /v1/banks/{code} não achou COMPE nem ISPB no catálogo (ou a linha está desabilitada). | não |
banking_unavailable | 503 | O provedor bancário não está disponível para esta operação neste momento. Repita em alguns segundos; nada foi executado. | sim |
beneficiary_check_unavailable | 503 | Não foi possível confirmar o destino da transferência interna por documento. Retente ou use /transfers/internal/by-bank-account. | não |
cognito_error | 502 | Falha no provedor de identidade ao criar ou alterar a credencial. Repita; se persistir, acione o suporte. | sim |
cognito_unavailable | 503 | Provedor de identidade indisponível. Repita em instantes. | sim |
credential_revoked | 403 | A credencial usada foi revogada. Gere uma nova credencial no internet banking (IB) ou com a CorpX (BaaS). | não |
db_error | 500 | Erro interno de persistência. | não |
db_unavailable | 503 | Banco de dados do gateway indisponível. Nada foi executado; repita em instantes. | sim |
evidence_not_approved | 422 | A evidência de biometria (biometry.evidenceId) ainda não passou pela verificação de conteúdo, ou foi recusada. Envie uma nova evidência. | não |
forbidden | 403 | Você não tem permissão para realizar esta ação no recurso solicitado. | não |
holder_not_pj | 422 | Pedido de atualização cadastral é só de conta PJ. PF usa PUT /holder/address. | não |
holder_update_closed | 409 | O pedido não está no estado que aceita esta ação. | não |
holder_update_document_type_invalid | 422 | documentType não faz parte deste pedido. | não |
holder_update_documents_missing | 422 | Falta documento obrigatório com scanStatus APPROVED. | não |
holder_update_kind_invalid | 422 | kind deve ser address ou registration. | não |
holder_update_not_found | 404 | Pedido de atualização não encontrado nesta conta. | não |
holder_update_pending | 409 | Já existe um pedido aberto do mesmo tipo nesta conta. | não |
holder_update_required | 422 | Conta PJ não altera endereço direto. Abra um pedido em POST /v1/accounts/{accountId}/holder-updates com comprovante. | não |
idempotency_conflict | 409 | A Idempotency-Key já foi usada por outro tenant em um endpoint que deriva identificadores dela (fluxos habilitados sob demanda). Reenviar uma Idempotency-Key com corpo diferente não devolve conflito nos demais endpoints: você recebe o resultado da operação original. Ver Idempotência. | não |
identity_not_approved | 409 | A verificação de identidade da jornada de consent ainda não foi aprovada. A jornada permanece pendente; o titular refaz a captura pelo mesmo link. | não |
identity_stale | 409 | A verificação de identidade expirou. A jornada permanece pendente; o titular refaz a captura pelo mesmo link. | não |
ingest_unavailable | 503 | Componente interno de ingestão indisponível. Repita em instantes. | sim |
init_error | 500 | Falha ao inicializar dependências do gateway. Repita; se persistir, acione o suporte com o requestId. | sim |
insufficient_scope | 403 | A credencial não tem o escopo necessário para a rota (ex.: qrcode.manage, pix_out.create), ou é somente leitura tentando uma escrita. A mensagem nomeia o escopo que falta. Veja o Guia de Autenticação. | não |
integrator_credential_required | 403 | A rota movimenta dinheiro e exige credencial de integrador (client_credentials) emitida pela CorpX. Token de sessão de usuário do Portal é recusado mesmo quando o usuário tem acesso à conta. | não |
internal_error | 500 | Ocorreu um erro inesperado em nossos servidores. | não |
invalid_account | 400 | accountId informado para a credencial não é um UUID ou não pertence ao tenant. | não |
invalid_body | 400 | O corpo não é um JSON válido. | não |
invalid_client | 400 | clientId mal formado. | não |
invalid_path | 400 | Um segmento do path está vazio ou mal formado (por exemplo transactionId ausente na timeline). | não |
invalid_scope | 400 | Um dos escopos pedidos para a credencial não existe. Veja a lista em Autenticação. | não |
invalid_state | 409 | A operação não se aplica ao estado atual do recurso. | não |
marshal_error | 500 | Falha interna ao serializar a resposta. Repita; se persistir, acione o suporte com o requestId. | sim |
med_request_closed | 409 | A contestação não está no estado que aceita esta ação. | não |
med_request_info_missing | 422 | Reenviar depois de um pedido de informação exige mensagem ou anexo aprovado. | não |
med_request_not_found | 404 | Contestação não encontrada nesta conta. | não |
med_request_not_outgoing_pix | 422 | Só um PIX enviado por esta conta pode ser contestado. | não |
med_request_out_of_window | 422 | O PIX passou da janela de 80 dias para contestação. | não |
med_request_pending | 409 | Já existe contestação aberta para este endToEndId. | não |
method_not_allowed | 405 | O método HTTP não é aceito nesta rota. Confira o método na referência da API. | não |
missing_idempotency_key | 400 | O header Idempotency-Key é obrigatório. | não |
missing_tenant | 400 | O header X-Tenant-Id é obrigatório e não foi informado. | não |
no_accounts | 404 | O tenant ainda não tem nenhuma conta. Conclua a abertura de conta antes de operar. | não |
payload_too_large | 413 | Corpo da requisição acima do limite da rota (evidência de MED: 10 MB). Reduza o arquivo ou use a URL de upload. | não |
pix_transaction_not_found | 404 | O endToEndId não é um PIX desta conta. | não |
rate_check_unavailable | 503 | Não foi possível validar o limite de jornadas agora. Retente em instantes. | não |
request_in_progress | 409 | A mesma Idempotency-Key já está em processamento neste tenant. Aguarde e consulte de novo; não é um segundo encerramento. | sim |
scope_not_self_service | 403 | Esse escopo só pode ser concedido pela CorpX, não pela própria credencial. | não |
storage_error | 502 | Falha ao gravar ou ler o arquivo de evidência. Repita; se persistir, acione o suporte. | sim |
temporal_unavailable | 503 | O orquestrador de operações assíncronas não respondeu; a operação não foi iniciada. Repita com a mesma Idempotency-Key. | sim |
tenant_disabled | 403 | O tenant está desativado: nenhuma rota da API responde. Fale com o suporte CorpX para reativar o acesso. | não |
tenant_forbidden | 403 | O token não está autorizado para o tenant do X-Tenant-Id. Vale para qualquer rota /v1/: a credencial e o header precisam apontar para o mesmo tenant. | não |
tenant_mismatch | 403 | O X-Tenant-Id não corresponde ao tenant da conta no path (ou ao tenantId do body). | não |
tenant_suspended | 403 | Há uma pendência em aberto e as operações de escrita estão suspensas. Consultas seguem funcionando. Fale com o suporte CorpX para regularizar. | não |
unauthorized | 401 | Header Authorization ausente. Token inválido ou expirado retorna 403 (obtenha um novo token via client_credentials). | não |
unsupported_media_type | 422 | Tipo de arquivo não aceito para evidência de MED. Envie PDF, PNG ou JPEG. | não |
user_token_forbidden_on_financial_op | 403 | Token de usuário não movimenta dinheiro: operações financeiras exigem credencial de aplicação (client_credentials). | não |
workflow_start_failed | 500 | Não foi possível iniciar a operação assíncrona. Repita com a mesma Idempotency-Key; se persistir, acione o suporte. | sim |
workflow_timeout | 504 | A operação não concluiu dentro da janela síncrona. O resultado é indeterminado: consulte o extrato ou o status antes de repetir. | não |
Liquidante
Recusas do banco liquidante traduzidas para código estável. O bloco partner traz o original.
PIX out
| Código | HTTP | O que aconteceu e o que fazer | Retentativa |
|---|---|---|---|
batch_not_found | 404 | BigPix: o batchId consultado não existe. | não |
batch_too_large | 400 | BigPix: o valor pedido geraria mais de 99 parcelas. | não |
beneficiary_incomplete | 422 | O beneficiário cadastrado não tem todos os dados necessários para a operação escolhida. | não |
beneficiary_not_active_at_partner | 422 | O beneficiário existe no cadastro mas ainda não está ativo no liquidante. | não |
beneficiary_not_found | 404 | O beneficiário informado não existe no cadastro da conta. | não |
dict_lookup_limit_exceeded | 429 | Os limites de consulta DICT foram atingidos: uma contagem absoluta (maxLookupsPerDay, maxLookupsPerMinute, maxNotFoundPer5min) ou uma taxa por janela de tempo (consultas por transferência, ou fração de consultas que não resolvem chave, de 5 min a 30 dias). Valem os da policy do tenant/conta e, para os campos não preenchidos, o default global — sempre contados por conta, nunca somados no tenant. A mensagem indica qual contador ou janela disparou. Aguarde a janela renovar (00:00 BRT para o limite diário; janela deslizante para as taxas) ou ajuste os limites no Backoffice. Consumo abusivo é acompanhado e tem consequências — ver Consultas de chave PIX. | não |
invalid_amount | 400 | amount ausente, não positivo ou com mais de duas casas decimais. | não |
invalid_bank_code | 400 | No PIX por dados bancários, bankCode aceita o Compe de 3 dígitos ou o ISPB de 8 dígitos. Em TED só o Compe é aceito — ver TED. | não |
invalid_identifier | 400 | O identifier excede o tamanho aceito, usa caracteres não permitidos, ou — no pedido de aumento de limite — não é idêntico ao header Idempotency-Key. | não |
invalid_pix_batch_policy | 400 | pixBatch.maxItems deve ser inteiro entre 1 e 5000 e pixBatch.enabled deve ser booleano. | não |
pix_batch_account_disabled | 403 | PIX em lote não está habilitado nesta conta. pixBatch.enabled=true na policy do tenant libera todas as contas; na policy da conta, só ela. Ajuste feito pela CorpX. | não |
<a id=“pix_batch_acknowledgement_required”></a>pix_batch_acknowledgement_required | 409 | O dispatch precisa de {“acknowledged”: true} confirmando que o resumo da conferência (valores, saldo e limites) foi lido. | não |
pix_batch_chunk_invalid | 400 | Cada PUT de itens deve conter entre 1 e 50 pagamentos válidos; o corpo lista as linhas rejeitadas em errors[] e nada foi salvo. | não |
pix_batch_csv_invalid | 400 | O CSV não segue o modelo (cabeçalho, separador ou linhas inválidas) ou excede 5 MiB (413). errors[] aponta linha e campo; nada foi salvo. | não |
pix_batch_empty | 409 | O lote não tem itens para conferir ou disparar. | não |
pix_batch_has_invalid_items | 409 | A conferência marcou itens inválidos (chave inexistente, identifier já usado, acima do limite por operação…). Baixe o CSV de correção em GET …/items/export?status=invalid, corrija ou remova e confira de novo. | não |
pix_batch_insufficient_balance | 422 | O saldo disponível no momento do dispatch é menor que o total do lote. Nenhum item foi iniciado. | não |
pix_batch_item_conflict | 409 | O identifier já existe no lote com outro conteúdo. Repetir o mesmo identifier com o mesmo conteúdo é aceito sem efeito. | não |
pix_batch_item_not_found | 404 | Item do lote de PIX não encontrado. | não |
pix_batch_limit_exceeded | 422 | A conferência mostrou que o total do lote passa de um limite de saída da conta (review.limits com sufficient=false). Sem esta recusa os primeiros PIX sairiam e os seguintes falhariam por limite. Remova itens ou aguarde a janela do limite e confira de novo. Nenhum item foi iniciado. | não |
pix_batch_no_receipts | 409 | Comprovantes só existem para lotes encerrados (COMPLETED, PARTIAL_FAILED ou FAILED) com ao menos um item liquidado. | não |
pix_batch_not_editable | 409 | Só lotes DRAFT ou REVIEWED aceitam alteração de itens ou nova conferência. Depois do dispatch o lote é imutável. | não |
pix_batch_not_found | 404 | Lote de PIX não encontrado nesta conta. | não |
pix_batch_not_reviewed | 409 | O dispatch exige um lote REVIEWED com todos os itens conferidos. Chame POST …/review e aguarde o status. | não |
pix_batch_receipt_unavailable | 409 | O item ainda não liquidou (ou falhou); só itens COMPLETED têm comprovante. | não |
pix_batch_too_large | 400 | O lote ultrapassa o máximo de itens da conta (pixBatch.maxItems; padrão 50, teto 5.000). A mensagem traz o limite efetivo e sua origem. | não |
policy_denied | 422 | Uma regra de política configurada para a conta ou tenant recusou a operação — transferência, criação de QR Code, criação de chave PIX ou estorno. O corpo traz violations com rule e message de cada regra violada. Ver Políticas e Regras. | não |
receipt_render_failed | 500 | Falha ao gerar o PDF do comprovante. Tente novamente; o pagamento em si não é afetado. | sim |
QR Code
Chaves PIX
Devolução
TED
Transferência interna
Extrato, lançamentos e exportações
Webhooks
| Código | HTTP | O que aconteceu e o que fazer | Retentativa |
|---|---|---|---|
account_id_required | 422 | A credencial está restrita a contas específicas: informe accountId na subscription. Ver Assinatura por conta. | não |
hookdeck_list_failed | 502 | O serviço de entregas não conseguiu listar as tentativas. Repita em instantes. | sim |
hookdeck_retry_failed | 502 | O serviço de entregas recusou o reenvio. Repita em instantes. | sim |
hookdeck_source_unavailable | 503 | Fonte de entregas do tenant indisponível no serviço de webhooks. Repita em instantes. | sim |
hookdeck_sync_failed | 502 | Falha ao registrar o destino no nosso entregador de webhooks. Pode ser repetido. | não |
hookdeck_unavailable | 503 | Serviço de entregas de webhook indisponível. Repita em instantes. | sim |
invalid_url | 400 | A url precisa usar https://. | não |
missing_delivery_id | 400 | deliveryId ausente no path. | não |
missing_subscription_id | 400 | subscriptionId ausente no path. | não |
no_hookdeck_destination | 410 | A subscription não tem mais destino de entrega ativo. Recrie a subscription. | não |
no_hookdeck_event_found | 410 | A entrega saiu da janela de retenção e não pode mais ser reenviada. | não |
reemit_failed | 500 | Falha ao reemitir o evento. Repita; se persistir, acione o suporte com o deliveryId. | sim |
replay_already_running | 409 | Já existe um replay em andamento para esta subscription. Aguarde a conclusão. | não |
unsupported_auth_type | 400 | authType da subscription fora dos valores aceitos (NONE, HMAC, BASIC, BEARER). | não |
Assinatura de requisição (host assinado)
Segurança da conta (travas, PIN e limites)
Boleto Charge
Emissão e consulta de boletos da própria conta (Boleto Charge). Distinto de Boleto Pay, que paga um boleto de terceiro.
Bloqueios de saldo
Bloquear parte do saldo, liberar para outra conta CorpX e cancelar.
P2P Cripto
Mercado P2P de stablecoins: perfis, carteiras, anúncios, ordens, assinatura e disputas.