Every error response has the same body. Branch on errorCode, never on
message — the text is presentation and may change; the code is contract.
{"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" }}
| Field | What it is |
|---|---|
errorCode | Stable code. The list below is generated from the gateway source on every release. |
message | Portuguese explanation for logs and support. Do not parse it. |
docs | Link to the code’s anchor on this page. |
requestId | Gateway request id. Quote it when opening a ticket. |
partner | Only when the failure came from the settlement bank: its raw error, for diagnosis. |
New codes may appear without a version bump. Treat an unknown errorCode
as a generic error of the same HTTP status: 4xx means the request is wrong
(do not retry unchanged); 5xx and retryable: yes can be retried with the
same Idempotency-Key.
General
Authentication, headers, format and availability. Can happen on any route.
| Code | HTTP | What happened and what to do | Retryable |
|---|---|---|---|
account_blocked | 423 | The account was operationally blocked by CorpX. Queries and incoming funds remain available, but outgoing financial operations are refused until it is unblocked. | no |
account_has_balance | 422 | POST /v1/accounts/{accountId}/close on the exclusive path: the settlement bank still holds an available balance (available ≠ 0, or total ≠ 0 with nothing locked). Withdraw it first. The body carries the raw settlement-bank balance. | no |
account_has_locked_balance | 422 | POST /v1/accounts/{accountId}/close on the exclusive path: the available balance is zero, but the settlement bank still holds a locked balance (locked ≠ 0, e.g. a MED hold). The account can only be closed after the lock is released. The body carries the raw settlement-bank balance. | no |
account_has_pix_keys | 422 | POST /v1/accounts/{accountId}/close on the exclusive path: the account still has a PIX key at the settlement bank. Delete the keys first. The body lists key types only, not the key value. | no |
account_holder_missing | 404 | The settlement bank did not return the account holder. | no |
account_not_found | 404 | The accountId in the path does not exist. | no |
acting_not_holder | 403 | X-Acting-Document is not the account holder’s document. | no |
bank_not_found | 404 | GET /v1/banks/{code} did not find that COMPE or ISPB in the catalog (or the row is disabled). | no |
banking_unavailable | 503 | The banking provider is not available for this operation right now. Retry in a few seconds; nothing was executed. | yes |
beneficiary_check_unavailable | 503 | Could not confirm the internal-transfer destination by document. Retry or use /transfers/internal/by-bank-account. | no |
cognito_error | 502 | Identity provider failure while creating or changing the credential. Retry; if it persists, contact support. | yes |
cognito_unavailable | 503 | Identity provider unavailable. Retry shortly. | yes |
credential_revoked | 403 | The credential used has been revoked. Issue a new one in the internet banking (IB) or with CorpX (BaaS). | no |
db_error | 500 | Internal persistence error. | no |
db_unavailable | 503 | Gateway database unavailable. Nothing was executed; retry shortly. | yes |
evidence_not_approved | 422 | The biometry evidence (biometry.evidenceId) has not passed content verification yet, or was rejected. Upload new evidence. | no |
forbidden | 403 | You do not have permission to perform this action on the requested resource. | no |
holder_not_pj | 422 | A holder update is only for a company account. A person uses PUT /holder/address. | no |
holder_update_closed | 409 | The request is not in a state that accepts this action. | no |
holder_update_document_type_invalid | 422 | documentType is not part of this request. | no |
holder_update_documents_missing | 422 | A required document with scanStatus APPROVED is missing. | no |
holder_update_kind_invalid | 422 | kind must be address or registration. | no |
holder_update_not_found | 404 | Holder update not found on this account. | no |
holder_update_pending | 409 | An open request of the same kind already exists for this account. | no |
holder_update_required | 422 | A company account cannot change its address directly. Open a holder update with proof of address. | no |
idempotency_conflict | 409 | The Idempotency-Key was already used by another tenant on an endpoint that derives identifiers from it (flows enabled on request). Reusing an Idempotency-Key with a different body does not return a conflict on the other endpoints: you get the result of the original operation. See Idempotency. | no |
identity_not_approved | 409 | Identity verification for the consent journey is not approved yet. The journey stays pending; the holder recaptures via the same link. | no |
identity_stale | 409 | Identity verification expired. The journey stays pending; the holder recaptures via the same link. | no |
ingest_unavailable | 503 | Internal ingestion component unavailable. Retry shortly. | yes |
init_error | 500 | Failed to initialise gateway dependencies. Retry; if it persists, contact support with the requestId. | yes |
insufficient_scope | 403 | The credential lacks the scope required by the route (e.g. qrcode.manage, pix_out.create), or is read-only attempting a write. The message names the missing scope. See the Authentication Guide. | no |
integrator_credential_required | 403 | The route moves money and requires an integrator credential (client_credentials) issued by CorpX. A Portal user session token is refused even when that user has access to the account. | no |
internal_error | 500 | An unexpected error occurred on our servers. | no |
invalid_account | 400 | The accountId given for the credential is not a UUID or does not belong to the tenant. | no |
invalid_body | 400 | The body is not valid JSON. | no |
invalid_client | 400 | Malformed clientId. | no |
invalid_path | 400 | A path segment is empty or malformed (for example a missing transactionId on the timeline route). | no |
invalid_scope | 400 | One of the scopes requested for the credential does not exist. See the list under Authentication. | no |
invalid_state | 409 | The operation does not apply to the resource’s current state. | no |
marshal_error | 500 | Internal failure while serialising the response. Retry; if it persists, contact support with the requestId. | yes |
med_request_closed | 409 | The contestation is not in a state that accepts this action. | no |
med_request_info_missing | 422 | Resubmitting after an information request requires a message or an approved attachment. | no |
med_request_not_found | 404 | Contestation not found on this account. | no |
med_request_not_outgoing_pix | 422 | Only a PIX sent by this account can be contested. | no |
med_request_out_of_window | 422 | The PIX is outside the 80-day contestation window. | no |
med_request_pending | 409 | An open contestation already exists for this endToEndId. | no |
method_not_allowed | 405 | The HTTP method is not accepted on this route. Check the method in the API reference. | no |
missing_idempotency_key | 400 | The Idempotency-Key header is required. | no |
missing_tenant | 400 | The X-Tenant-Id header is required and was not provided. | no |
no_accounts | 404 | The tenant has no accounts yet. Finish account opening before operating. | no |
payload_too_large | 413 | Request body exceeds the route limit (MED evidence: 10 MB). Shrink the file or use the upload URL. | no |
pix_transaction_not_found | 404 | The endToEndId is not a PIX of this account. | no |
rate_check_unavailable | 503 | Could not validate the journey rate limit right now. Retry in a moment. | no |
request_in_progress | 409 | The same Idempotency-Key is already being processed for this tenant. Wait and retry; this is not a second close. | yes |
scope_not_self_service | 403 | This scope can only be granted by CorpX, not by the credential itself. | no |
storage_error | 502 | Failed to store or read the evidence file. Retry; if it persists, contact support. | yes |
temporal_unavailable | 503 | The async operation orchestrator did not respond; the operation was not started. Retry with the same Idempotency-Key. | yes |
tenant_disabled | 403 | The tenant is disabled: no API route responds. Contact CorpX support to restore access. | no |
tenant_forbidden | 403 | The token is not authorized for the tenant in X-Tenant-Id. Applies to every /v1/ route: credential and header must point to the same tenant. | no |
tenant_mismatch | 403 | X-Tenant-Id does not match the tenant of the account in the path (or the body’s tenantId). | no |
tenant_suspended | 403 | There is an open pendency and write operations are suspended. Reads keep working. Contact CorpX support to clear it. | no |
unauthorized | 401 | Missing Authorization header. An invalid or expired token returns 403 (obtain a new token via client_credentials). | no |
unsupported_media_type | 422 | File type not accepted as MED evidence. Send PDF, PNG or JPEG. | no |
user_token_forbidden_on_financial_op | 403 | User tokens cannot move money: financial operations require an application credential (client_credentials). | no |
workflow_start_failed | 500 | The asynchronous operation could not be started. Retry with the same Idempotency-Key; if it persists, contact support. | yes |
workflow_timeout | 504 | The operation did not finish inside the synchronous window. The outcome is indeterminate: check the statement or status before retrying. | no |
Settlement bank
Rejections from the settlement bank translated to stable codes. The partner block carries the original.
PIX out
| Code | HTTP | What happened and what to do | Retryable |
|---|---|---|---|
batch_not_found | 404 | BigPix: the requested batchId does not exist. | no |
batch_too_large | 400 | BigPix: the requested amount would produce more than 99 chunks. | no |
beneficiary_incomplete | 422 | The stored beneficiary lacks data required by the chosen operation. | no |
beneficiary_not_active_at_partner | 422 | The beneficiary exists locally but is not active at the provider yet. | no |
beneficiary_not_found | 404 | The given beneficiary does not exist in the account’s address book. | no |
dict_lookup_limit_exceeded | 429 | DICT lookup limits were exceeded: either an absolute count (maxLookupsPerDay, maxLookupsPerMinute, maxNotFoundPer5min) or a rate over a time window (lookups per transfer, or the fraction of lookups resolving no key, from 5 min to 30 days). Both the tenant/account policy and, for fields left blank, the global default apply — always counted per account, never summed across the tenant. The message indicates which counter or window triggered. Wait for the window to reset (00:00 BRT for per-day; sliding for the rates) or adjust the limits in the Backoffice. Abusive consumption is monitored and has consequences — see PIX key lookups. | no |
invalid_amount | 400 | amount missing, not positive, or with more than two decimal places. | no |
invalid_bank_code | 400 | On PIX by bank-account details, bankCode accepts a 3-digit Compe code or an 8-digit ISPB. TED accepts only the Compe code — see TED. | no |
invalid_identifier | 400 | identifier exceeds the accepted length, uses disallowed characters, or — on a limit increase — is not identical to the Idempotency-Key header. | no |
invalid_pix_batch_policy | 400 | pixBatch.maxItems must be an integer between 1 and 5000 and pixBatch.enabled must be a boolean. | no |
pix_batch_account_disabled | 403 | Batch PIX is not enabled for this account. pixBatch.enabled=true on the tenant policy enables every account; on the account policy, only that account. Set by CorpX staff. | no |
<a id=“pix_batch_acknowledgement_required”></a>pix_batch_acknowledgement_required | 409 | Dispatch requires {“acknowledged”: true} confirming the review summary (amounts, balance and limits) was read. | no |
pix_batch_chunk_invalid | 400 | Each items PUT must contain between 1 and 50 valid payments; the body lists the rejected rows in errors[] and nothing was saved. | no |
pix_batch_csv_invalid | 400 | The CSV does not follow the template (header, separator or invalid rows) or exceeds 5 MiB (413). errors[] points to line and field; nothing was saved. | no |
pix_batch_empty | 409 | The batch has no items to review or dispatch. | no |
pix_batch_has_invalid_items | 409 | Review flagged invalid items (missing key, identifier already used, above the per-operation limit…). Download the correction CSV from GET …/items/export?status=invalid, fix or remove them and review again. | no |
pix_batch_insufficient_balance | 422 | The available balance at dispatch time is lower than the batch total. No item was started. | no |
pix_batch_item_conflict | 409 | The identifier already exists in the batch with different content. Repeating the same identifier with the same content is a no-op. | no |
pix_batch_item_not_found | 404 | PIX batch item not found. | no |
pix_batch_limit_exceeded | 422 | The review showed the batch total exceeds an account outbound limit (review.limits with sufficient=false). Without this refusal the first PIX would go out and the rest would fail on the limit. Remove items or wait for the limit window and review again. No item was started. | no |
pix_batch_no_receipts | 409 | Receipts only exist for finished batches (COMPLETED, PARTIAL_FAILED or FAILED) with at least one settled item. | no |
pix_batch_not_editable | 409 | Only DRAFT or REVIEWED batches accept item changes or a new review. After dispatch the batch is immutable. | no |
pix_batch_not_found | 404 | PIX batch not found in this account. | no |
pix_batch_not_reviewed | 409 | Dispatch requires a REVIEWED batch with every item checked. Call POST …/review and wait for the status. | no |
pix_batch_receipt_unavailable | 409 | The item has not settled yet (or failed); only COMPLETED items have a receipt. | no |
pix_batch_too_large | 400 | The batch exceeds the account’s maximum item count (pixBatch.maxItems; default 50, hard cap 5,000). The message carries the effective limit and its source. | no |
policy_denied | 422 | A policy rule configured for the account or tenant refused the operation — transfer, QR code creation, PIX key creation, or refund. The body carries violations with the rule and message of each violated rule. See Policies and Rules. | no |
receipt_render_failed | 500 | Failed to render the receipt PDF. Retry; the payment itself is not affected. | yes |
QR Code
PIX keys
Refund
TED
Internal transfer
Statement, entries and exports
Webhooks
| Code | HTTP | What happened and what to do | Retryable |
|---|---|---|---|
account_id_required | 422 | The credential is restricted to specific accounts: pass accountId on the subscription. See Per-account subscriptions. | no |
hookdeck_list_failed | 502 | The delivery service could not list the attempts. Retry shortly. | yes |
hookdeck_retry_failed | 502 | The delivery service refused the retry. Retry shortly. | yes |
hookdeck_source_unavailable | 503 | The tenant’s delivery source is unavailable in the webhook service. Retry shortly. | yes |
hookdeck_sync_failed | 502 | Failed to register the destination at our webhook delivery service. Safe to retry. | no |
hookdeck_unavailable | 503 | Webhook delivery service unavailable. Retry shortly. | yes |
invalid_url | 400 | url must use https://. | no |
missing_delivery_id | 400 | deliveryId missing from the path. | no |
missing_subscription_id | 400 | subscriptionId missing from the path. | no |
no_hookdeck_destination | 410 | The subscription no longer has an active delivery destination. Recreate the subscription. | no |
no_hookdeck_event_found | 410 | The delivery is past the retention window and can no longer be resent. | no |
reemit_failed | 500 | Failed to re-emit the event. Retry; if it persists, contact support with the deliveryId. | yes |
replay_already_running | 409 | A replay is already running for this subscription. Wait for it to finish. | no |
unsupported_auth_type | 400 | Subscription authType outside the accepted values (NONE, HMAC, BASIC, BEARER). | no |
Request signing (signed host)
Account security (locks, PIN and limits)
Boleto Charge
Issuing and consulting boletos of the account itself (Boleto Charge). Distinct from Boleto Pay, which pays someone else’s boleto.
Balance holds
Hold part of the balance, release it to another CorpX account, or cancel it.
P2P Crypto
P2P stablecoin market: profiles, wallets, ads, orders, signing and disputes.