Skip to navigation

Errors

Every errorCode the API returns, generated from the code that emits it.

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" }
}
FieldWhat it is
errorCodeStable code. The list below is generated from the gateway source on every release.
messagePortuguese explanation for logs and support. Do not parse it.
docsLink to the code’s anchor on this page.
requestIdGateway request id. Quote it when opening a ticket.
partnerOnly when the failure came from the settlement bank: its raw error, for diagnosis.
Open enum

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.

CodeHTTPWhat happened and what to doRetryable
account_blocked423The 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_balance422POST /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_balance422POST /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_keys422POST /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_missing404The settlement bank did not return the account holder.no
account_not_found404The accountId in the path does not exist.no
acting_not_holder403X-Acting-Document is not the account holder’s document.no
bank_not_found404GET /v1/banks/{code} did not find that COMPE or ISPB in the catalog (or the row is disabled).no
banking_unavailable503The banking provider is not available for this operation right now. Retry in a few seconds; nothing was executed.yes
beneficiary_check_unavailable503Could not confirm the internal-transfer destination by document. Retry or use /transfers/internal/by-bank-account.no
cognito_error502Identity provider failure while creating or changing the credential. Retry; if it persists, contact support.yes
cognito_unavailable503Identity provider unavailable. Retry shortly.yes
credential_revoked403The credential used has been revoked. Issue a new one in the internet banking (IB) or with CorpX (BaaS).no
db_error500Internal persistence error.no
db_unavailable503Gateway database unavailable. Nothing was executed; retry shortly.yes
evidence_not_approved422The biometry evidence (biometry.evidenceId) has not passed content verification yet, or was rejected. Upload new evidence.no
forbidden403You do not have permission to perform this action on the requested resource.no
holder_not_pj422A holder update is only for a company account. A person uses PUT /holder/address.no
holder_update_closed409The request is not in a state that accepts this action.no
holder_update_document_type_invalid422documentType is not part of this request.no
holder_update_documents_missing422A required document with scanStatus APPROVED is missing.no
holder_update_kind_invalid422kind must be address or registration.no
holder_update_not_found404Holder update not found on this account.no
holder_update_pending409An open request of the same kind already exists for this account.no
holder_update_required422A company account cannot change its address directly. Open a holder update with proof of address.no
idempotency_conflict409The 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_approved409Identity verification for the consent journey is not approved yet. The journey stays pending; the holder recaptures via the same link.no
identity_stale409Identity verification expired. The journey stays pending; the holder recaptures via the same link.no
ingest_unavailable503Internal ingestion component unavailable. Retry shortly.yes
init_error500Failed to initialise gateway dependencies. Retry; if it persists, contact support with the requestId.yes
insufficient_scope403The 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_required403The 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_error500An unexpected error occurred on our servers.no
invalid_account400The accountId given for the credential is not a UUID or does not belong to the tenant.no
invalid_body400The body is not valid JSON.no
invalid_client400Malformed clientId.no
invalid_path400A path segment is empty or malformed (for example a missing transactionId on the timeline route).no
invalid_scope400One of the scopes requested for the credential does not exist. See the list under Authentication.no
invalid_state409The operation does not apply to the resource’s current state.no
marshal_error500Internal failure while serialising the response. Retry; if it persists, contact support with the requestId.yes
med_request_closed409The contestation is not in a state that accepts this action.no
med_request_info_missing422Resubmitting after an information request requires a message or an approved attachment.no
med_request_not_found404Contestation not found on this account.no
med_request_not_outgoing_pix422Only a PIX sent by this account can be contested.no
med_request_out_of_window422The PIX is outside the 80-day contestation window.no
med_request_pending409An open contestation already exists for this endToEndId.no
method_not_allowed405The HTTP method is not accepted on this route. Check the method in the API reference.no
missing_idempotency_key400The Idempotency-Key header is required.no
missing_tenant400The X-Tenant-Id header is required and was not provided.no
no_accounts404The tenant has no accounts yet. Finish account opening before operating.no
payload_too_large413Request body exceeds the route limit (MED evidence: 10 MB). Shrink the file or use the upload URL.no
pix_transaction_not_found404The endToEndId is not a PIX of this account.no
rate_check_unavailable503Could not validate the journey rate limit right now. Retry in a moment.no
request_in_progress409The same Idempotency-Key is already being processed for this tenant. Wait and retry; this is not a second close.yes
scope_not_self_service403This scope can only be granted by CorpX, not by the credential itself.no
storage_error502Failed to store or read the evidence file. Retry; if it persists, contact support.yes
temporal_unavailable503The async operation orchestrator did not respond; the operation was not started. Retry with the same Idempotency-Key.yes
tenant_disabled403The tenant is disabled: no API route responds. Contact CorpX support to restore access.no
tenant_forbidden403The 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_mismatch403X-Tenant-Id does not match the tenant of the account in the path (or the body’s tenantId).no
tenant_suspended403There is an open pendency and write operations are suspended. Reads keep working. Contact CorpX support to clear it.no
unauthorized401Missing Authorization header. An invalid or expired token returns 403 (obtain a new token via client_credentials).no
unsupported_media_type422File type not accepted as MED evidence. Send PDF, PNG or JPEG.no
user_token_forbidden_on_financial_op403User tokens cannot move money: financial operations require an application credential (client_credentials).no
workflow_start_failed500The asynchronous operation could not be started. Retry with the same Idempotency-Key; if it persists, contact support.yes
workflow_timeout504The 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.

CodeHTTPWhat happened and what to doRetryable
account_not_entitled409The account is fully accredited, but the banking provider has not enabled this service for it — other operations on the same account keep working. This is neither a transient failure nor a problem with your request: retrying will not help until the provider enables it. Contact support with the accountId.no
account_not_ready409The account has no counterpart at the banking provider yet — accreditation is in progress, was refused, or never completed. This is not an API outage: no banking operation works on this account until the accreditation reaches ACTIVE.no
already_at_partner409The document is already accredited at the banking provider by another participant. Requires a control transfer through support.no
automatic_pix_contract_blocked409The arrangement blocks the same contract within 24 hours, a pending authorization for the same contract and payer, and an identical proposal rejected or canceled less than 30 days ago. Wait for the payer or use another contract number.no
automatic_pix_date_out_of_window422A scheduling due date must fall in the current cycle at least 2 days ahead; a retry must be after the original due date, within 7 calendar days and the same cycle. Fetch the suggested dates before requesting a retry.no
automatic_pix_identifier_in_use409The composite QR Code identifier was already used on this account. Each composite QR needs its own identifier.no
automatic_pix_payer_bank_unavailable422The informed ISPB does not exist or is not active for Automatic Pix. Check the payer’s bank.no
automatic_pix_receiver_ineligible422The Automatic Pix receiver must be an active legal entity with complete bank data at the settlement bank.no
automatic_pix_recurrence_not_authorized409Schedulings, postponements and retries only apply to a recurrence with status authorized.no
automatic_pix_retry_not_allowed409A retry requires paymentRetry=true on the recurrence, an unsettled settlement, no attempt in progress on the same day and unused dates, up to 3.no
automatic_pix_scheduling_conflict409Each cycle accepts one active scheduling. Postponing only works while the scheduling is created.no
automatic_pix_value_above_payer_limit422In a variable-amount recurrence, each charge respects the proposal maximumValue and the payerMaximumValue set by the payer.no
automatic_pix_value_mismatch422A fixed-amount recurrence charges exactly value; a variable one requires value on the scheduling. On creation, value and maximumValue are mutually exclusive.no
bacen_rejected_content400Text content (description/message) contains a character the Brazilian Central Bank does not accept.no
balance_reservation_failed422Balance reservation failed (funds locked, settling, or racing with another operation).no
boleto_already_settled409The bank slip is already settled. Check the original payment before resending.no
boleto_amount_mismatch422Amount differs from the registered bank slip amount (consider interest, fine and discount).no
boleto_charge_barcode_active409Rejected because a bank slip with this barcode is still active.no
boleto_charge_beneficiary_ineligible422The beneficiary is ineligible or under review. Retrying will not help until that changes.no
boleto_charge_discount_invalid422Discount limitDate is missing, unreadable, or not before the due date.no
boleto_charge_identifier_in_use409Issuance was rejected because the identifier is already active for this beneficiary.no
boleto_charge_not_eligible_for_write_off_cancel409Cancelling a write-off requires status writtenOff with a write-off in the arrangement. It does not cancel an open slip.no
boleto_charge_reductions_exceed_amount422Abatement plus discounts reach or exceed the face amount.no
boleto_charge_rules_inconsistent422A charge is inconsistent with the calculation model, or the min/max payment amounts disagree.no
boleto_scheduled409There is an active schedule for the same barcode.no
challenge_failure422PIN/2FA validation failed at the banking provider.no
conflict409State conflict at the banking provider (e.g. resource already processed).no
identifier_conflict409The Identifier was already used at the banking provider. Resending the same value does not create a new operation.no
insufficient_funds422Insufficient balance as computed by the banking provider at settlement time.no
invalid_field400Field-level validation at the banking provider. partner.field names the field and the message carries the limit when available.no
invalid_payload400The banking provider rejected the request body. The partner block carries the original validation message.no
invalid_pix_key400Key format does not match the declared type (CPF, CNPJ, EMAIL, PHONE, EVP).no
key_inactive422The key exists but is inactive or under portability. Use another key or bank details.no
key_not_found404Key not found in DICT. Check for typos or ask the recipient for another key.no
key_ownership_mismatch422Attempt to register or use a key whose document differs from the account holder’s.no
limit_exceeded422A limit was exceeded but the provider did not say which window.no
limit_exceeded_daily422For PIX, daytime window limit (06:00–20:00). For an internal transfer, São Paulo calendar-day limit (00:00–23:59). The message carries the remaining amount when available.no
limit_exceeded_monthly422Accumulated monthly limit. Only clears at month rollover or with a limit increase.no
limit_exceeded_nightly422Nighttime window limit (20:00–06:00), usually lower than the daytime one.no
limit_exceeded_transaction422Per-transaction limit. Split the operation or request a limit increase.no
not_found404Resource does not exist at the banking provider (id, key or transaction).no
not_supported501The route exists in the contract, but the settlement provider does not expose the operation. Retrying will not help — it is a missing capability, not an outage.no
partial_refund_not_supported400Legacy — no longer returned: partial refunds are now accepted. An amount above the original returns refund_amount_exceeded.no
partner_account_disabled422Source account is disabled at the banking provider (reactivation required).no
partner_error502Unclassified failure while talking to the banking provider. Safe to retry.yes
partner_forbidden502Operation blocked by the banking provider for this account (product or permission not enabled).no
partner_internal502Internal (5xx) error at the banking provider. Safe to retry.yes
partner_rate_limited429The banking provider throttled CorpX’s traffic. Nothing is wrong with your request — slow down and retry with backoff.yes
partner_rejected422Refused by the banking provider on internal policy, risk or fraud grounds. The partner block carries the stated reason.no
partner_unauthorized502CorpX’s own credential at the banking provider was rejected. Not related to your credential; wait a few minutes before resending.no
partner_unavailable502Provider outage or gateway failure. Safe to retry.yes
payer_key_required422The paying account needs at least one active PIX key to send. The problem is the source account, not the recipient’s key: register a key (a random key works) and retry.no
pix_key_limit_exceeded422Maximum number of keys per account reached (5 for individuals, 20 for companies).no
qr_amount_mismatch422A fixed-amount QR Code does not accept a different amount.no
qr_gone409QR Code removed or expired at the banking provider.no
recipient_account_not_found422Destination bank/branch/account does not exist. Applies to TED and internal transfers.no
refund_amount_exceeded400Refund amount is larger than the refundable balance of the original PIX.no
timeout504Timeout calling the banking provider. The operation may exist — query it before resending.yes

PIX out

CodeHTTPWhat happened and what to doRetryable
batch_not_found404BigPix: the requested batchId does not exist.no
batch_too_large400BigPix: the requested amount would produce more than 99 chunks.no
beneficiary_incomplete422The stored beneficiary lacks data required by the chosen operation.no
beneficiary_not_active_at_partner422The beneficiary exists locally but is not active at the provider yet.no
beneficiary_not_found404The given beneficiary does not exist in the account’s address book.no
dict_lookup_limit_exceeded429DICT 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_amount400amount missing, not positive, or with more than two decimal places.no
invalid_bank_code400On 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_identifier400identifier exceeds the accepted length, uses disallowed characters, or — on a limit increase — is not identical to the Idempotency-Key header.no
invalid_pix_batch_policy400pixBatch.maxItems must be an integer between 1 and 5000 and pixBatch.enabled must be a boolean.no
pix_batch_account_disabled403Batch 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_required409Dispatch requires {“acknowledged”: true} confirming the review summary (amounts, balance and limits) was read.no
pix_batch_chunk_invalid400Each 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_invalid400The 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_empty409The batch has no items to review or dispatch.no
pix_batch_has_invalid_items409Review 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_balance422The available balance at dispatch time is lower than the batch total. No item was started.no
pix_batch_item_conflict409The 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_found404PIX batch item not found.no
pix_batch_limit_exceeded422The 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_receipts409Receipts only exist for finished batches (COMPLETED, PARTIAL_FAILED or FAILED) with at least one settled item.no
pix_batch_not_editable409Only DRAFT or REVIEWED batches accept item changes or a new review. After dispatch the batch is immutable.no
pix_batch_not_found404PIX batch not found in this account.no
pix_batch_not_reviewed409Dispatch requires a REVIEWED batch with every item checked. Call POST …/review and wait for the status.no
pix_batch_receipt_unavailable409The item has not settled yet (or failed); only COMPLETED items have a receipt.no
pix_batch_too_large400The 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_denied422A 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_failed500Failed to render the receipt PDF. Retry; the payment itself is not affected.yes

QR Code

CodeHTTPWhat happened and what to doRetryable
missing_field400pixKey missing — and, on dynamic QR, value missing or not positive.no
missing_param400Lookup and cancellation require the identifier query param (alias txid).no

PIX keys

CodeHTTPWhat happened and what to doRetryable
key_type_temporarily_unavailable422Registering an email or phone key is temporarily unavailable. Use cpf, cnpj, or random. Listing and deleting those key types still works.no

Refund

CodeHTTPWhat happened and what to doRetryable
med_info_missing422The clarification cannot be submitted without a new message or attachment since the review’s request.no
med_lock_unavailable409The balance hold could not be placed or released: an amount is already held, the dispute is closed, or the settlement bank refused the operation.no
med_not_found404The dispute (MED) does not exist or does not belong to this account.no
med_not_writable409The dispute accepts no message or attachment right now: only in awaiting_defense (before the answer) or in info_requested.no
med_opened_by_us409The MED was opened by CorpX on the customer’s behalf (direction: opened): there is no defense, message, attachment or decision. Follow partnerStatus and lastUpdatedAt until the outcome.no
med_refund_amount_invalid422The return amount is required, positive, and cannot exceed what is left to return (remaining).no
med_refund_in_progress409A return for this dispute is still settling; wait for it to complete before the next step.no
med_refund_not_completed409The account is only released after the round’s return is completed and the remainder held.no
med_review_not_pending409The action requires the dispute under review (pending_review) or with a pending clarification (info_requested); it has already moved on.no
med_step_out_of_order409The requested step is not the next one in the round, or the dispute is not in execution. Return steps run one at a time, in order.no
original_transaction_not_found404The original transaction (originalEndToEnd) was not found.no

TED

CodeHTTPWhat happened and what to doRetryable
invalid_account_type400accountType must be CHECKING, SAVINGS, PAYMENT or SALARY. Omitted, it defaults to CHECKING.no
invalid_tax_number400taxNumber must have 11 (CPF) or 14 (CNPJ) digits.no
missing_fields400Missing value, holderName, branch, or account.no

Internal transfer

CodeHTTPWhat happened and what to doRetryable
multiple_destination_accounts409On /transfers/internal/by-document, the document has more than one active account. Address it by account instead: /transfers/internal/by-bank-account (branch + number) or /transfers/internal (destinationAccountId).no

Statement, entries and exports

CodeHTTPWhat happened and what to doRetryable
bucket_mismatch409The export file was produced in another environment and cannot be downloaded here. Create the export again.no
date_range_too_wide400The statement window exceeds 31 days. Split it into smaller periods.no
invalid_cursor400The pagination cursor is invalid or belongs to another query. Start over without cursor.no
invalid_date_range400startDate / endDate outside the YYYY-MM-DD format.no
invalid_filter400Invalid advanced statement filter (type, direction, status, minAmount/maxAmount or dates). The message names the field.no
invalid_format400Export format must be csv, pdf, or xlsx.no
invalid_operation400The entry detail requires the operation query param: PIX, TED, BOLETO, INTERNAL, or FEE.no
invalid_query400The per-account timeline requires exactly one of endToEndId and identifier — never both, never neither.no
invalid_s3_key500Internal reference to the export file is invalid. Create the export again; if it persists, contact support.yes
missing_account_id400accountId missing from the path. Use GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=....no
missing_identifier400Pass identifier or endToEnd in the query to locate the payment.no
not_ready409Download requested before the export finished. Poll the status until completed.no
presign_failed500Failed to generate the download link for an already finished file. Safe to retry.no
statement_rules_unavailable503Statement presentation rules have not loaded yet. Balance and amount do not change; only labels. Retry shortly.yes

Webhooks

CodeHTTPWhat happened and what to doRetryable
account_id_required422The credential is restricted to specific accounts: pass accountId on the subscription. See Per-account subscriptions.no
hookdeck_list_failed502The delivery service could not list the attempts. Retry shortly.yes
hookdeck_retry_failed502The delivery service refused the retry. Retry shortly.yes
hookdeck_source_unavailable503The tenant’s delivery source is unavailable in the webhook service. Retry shortly.yes
hookdeck_sync_failed502Failed to register the destination at our webhook delivery service. Safe to retry.no
hookdeck_unavailable503Webhook delivery service unavailable. Retry shortly.yes
invalid_url400url must use https://.no
missing_delivery_id400deliveryId missing from the path.no
missing_subscription_id400subscriptionId missing from the path.no
no_hookdeck_destination410The subscription no longer has an active delivery destination. Recreate the subscription.no
no_hookdeck_event_found410The delivery is past the retention window and can no longer be resent.no
reemit_failed500Failed to re-emit the event. Retry; if it persists, contact support with the deliveryId.yes
replay_already_running409A replay is already running for this subscription. Wait for it to finish.no
unsupported_auth_type400Subscription authType outside the accepted values (NONE, HMAC, BASIC, BEARER).no

Request signing (signed host)

CodeHTTPWhat happened and what to doRetryable
body_hash_mismatch400The received body does not match the signed X-Content-SHA256.no
credential_not_yet_active403Freshly issued credential still inside its grace period. Wait for the activeFrom returned at issue time.no
invalid_ip400Invalid address or CIDR in the IP allowlist. Use IPv4/IPv6 or CIDR notation (203.0.113.10/32).no
invalid_public_key422The PEM is not an EC P-256 or RSA ≥ 2048 public key. A private key PEM is rejected with its own message.no
ip_allowlist_derived409The tenant has delegated credentials: its IP allowlist is derived from them and does not accept manual edits.no
ip_allowlist_required422allowedIps missing, empty, longer than 20 entries, containing 0.0.0.0/0 or a prefix wider than /24.no
ip_not_allowed403The request came from an IP outside the credential’s allowlist.no
last_public_key409The credential’s last usable key cannot be retired.no
public_key_limit_reached409Public key limit per credential reached. Retire one before adding another.no
public_key_required422Issuing a delegated credential requires publicKeyPem.no
request_signature_invalid403The signature does not match the key announced in kid. Compare the canonical string via POST /v1/security/signature/verify; also check that the ES256 signature is `R\\
request_signature_required403Missing X-Request-Signature, X-Request-Timestamp or X-Content-SHA256.no
request_timestamp_skew403X-Request-Timestamp outside the 300s window. Sync the server clock (NTP).no
scope_not_delegable403The scope requested for the child credential is not held by the delegating credential, or is not delegable.no
signature_required403The request reached client.api.corpx.com without the signature headers. Edge block, before the token is looked at.no
signed_host_required403A delegated credential was used on tenant.api.corpx.com. Retry on client.api.corpx.com, signed.no
unknown_kid403The kid is not among the credential’s active keys: it was retired, or it is still inside the 18h grace period.no

Account security (locks, PIN and limits)

CodeHTTPWhat happened and what to doRetryable
acting_document_required400Send X-Acting-Document (the operator’s CPF) together with the PIN.no
cashout_locked423The account holder blocked money from leaving this account (cashoutBlocked).no
cashout_outside_hours403Outside the time window configured by the account holder. The message states the window.no
cashout_source_ip_not_allowed403The operation’s source IP is outside cashoutSourceIps. Integrators must pass the end user’s real IP in X-Acting-Ip.no
credential_not_found404The clientId in the path does not exist in this tenant.no
facetec_attempts_exhausted429The verification used up its 3 failed attempts (or the 15 total /facetec/process calls) and is FAILED. Create a new verification.no
facetec_match_unavailable422Face match against the requested reference (details.referenceMatch) is not available at the provider yet. Use referenceMatch: none (liveness only) or wait for availability. The API never silently downgrades to liveness-only.yes
facetec_process_in_progress409Another capture of this verification is being processed. Wait for the previous response (up to 15 s) before sending another.yes
facetec_sdk_not_enabled403method: facetec_sdk is not enabled for this tenant (feature identity_verification_facetec_sdk off or SDK keys not configured). Contact CorpX.no
facetec_session_expired409The FaceTec session token expired (10 min). Request a new one at /facetec/session and capture again; it does not count as an attempt.yes
facetec_session_renewal_limited429Too many session token renewals: at most 1 every 5 s and 30 per verification. Request a token only when about to open the camera.yes
facetec_unavailable503FaceTec SDK processing is temporarily unavailable at the provider. Retry shortly.yes
hash_error500Internal failure while protecting the PIN. Retry; if it persists, contact support.yes
identity_verification_kind_not_enabled403The tenant has no contracted quota for this verification kind (the kind’s monthlyLimits = 0). details.kind names it: link_unico, link_dracma, liveness, face_match_image or face_match_cpf. Contact CorpX to enable it.no
identity_verification_monthly_limit_exceeded429The contracted monthly quota of this verification kind (details.kind: link_unico, link_dracma, liveness, face_match_image or face_match_cpf) has been used in the BRT calendar month. The default is 10 for link kinds and 0 for SDK kinds when the policy does not set monthlyLimits. Every 201 counts and failure/expiry is not refunded.no
invalid_acting_document400X-Acting-Document must be a CPF (11 digits) or CNPJ (14 digits).no
invalid_cashout_hours422cashoutHours with an invalid HH:MM, start equal to end, or an unknown timezone.no
invalid_consume_ttl400consumeTtlMinutes must be between 1 and 60.no
invalid_display_message400displayMessage must be one-line plain text without links/markup and at most 240 characters.no
invalid_identity_verification_policy400identityVerification is tenant-scoped. monthlyLimit is an integer from 1 to 1000000; perDocumentPerHour and tenantPerMinute are integers from 1 to 1000. An absent field uses the default.no
invalid_justification400justification is required and has at most 500 characters.no
invalid_method400method must be link or facetec_sdk; facetec_sdk requires provider: dracma_trust.no
invalid_provider400provider must be unico or dracma_trust.no
invalid_purpose400purpose is not in the public identity-verification enum.no
invalid_reference_id400referenceId must contain 1–128 safe ASCII characters.no
invalid_reference_match400referenceMatch must be none, dracma or image and only applies to method: facetec_sdk.no
invalid_risk400risk.action must be allow, challenge or deny; risk.score, when sent, is between 0 and 1. A deny does not block the request — the block is only stored.no
invalid_verification_ttl400Identity-verification ttlMinutes must be between 1 and 60.no
limit_request_above_requested422The approved amount is above the request. Approval may be lower than or equal to the request, never higher.no
limit_request_bundle_required409The request belongs to a multi-operation bundle and must be decided through the bundle decision endpoint.no
limit_request_closed409The request was already approved, refused or cancelled and accepts no further decision or cancellation.no
limit_request_document_type_invalid422documentType is not in this account’s catalog (individual or company) and was not asked for by the reviewer.no
limit_request_documents_missing422Submitting for review is refused when a catalog type marked required has no antivirus-approved file. The current catalog marks none. details.missing lists the types.no
limit_request_info_missing422The reply to the information request is incomplete. details.missing lists the types (or message, when no file was requested).no
limit_request_not_above_current422The requested (or approved) amount is not above the account’s current effective limit.no
limit_request_not_found404The requestId does not exist on this account.no
limit_request_operation_unavailable422operation or window is not part of the limits contract (pix_out, ted_out, boleto, internal_out × single_transfer, daytime, nighttime, monthly).no
limit_request_pending409A limit increase for the same operation and window is already under review. Cancel it or wait for the decision.no
limits_unavailable503The limits service did not respond. Retry shortly.yes
no_pending_change404There is no scheduled loosening to cancel or bring forward.no
pin_change_disabled403Replacement without currentPin while hosted reset is on. A caller who knows the current PIN still changes it with PUT. Otherwise request a link with POST /v1/people/pin/reset-request; the operator chooses the new PIN on the CorpX page after the facial check. The first enrollment still uses PUT.no
pin_invalid403Wrong PIN. The attempt was counted.no
pin_locked4236 wrong attempts: unlocking requires resetting the PIN.no
pin_not_found404No PIN registered for the given operator.no
pin_not_set403This operator has no PIN registered in this tenant.no
pin_required428The credential requires X-Acting-Document and X-Transaction-Pin on cashout operations.no
pin_reset_not_enrolled409This operator has no PIN yet. The first enrollment is PUT /v1/people/pin. The per-account alias still accepts the same PUT.no
pin_reset_rate_limited429Too many PIN reset requests for this operator in the last hour. The Retry-After header carries the seconds.yes
pin_temporarily_locked4293 wrong attempts: locked for 15 minutes. The Retry-After header carries the seconds.no
provider_error502The verification provider returned an error. partner carries the raw detail when available. Capture again; it does not count as an attempt.yes
provider_session_starting409The facial session is already being created. Retry the same link.yes
provider_session_unavailable409The provider session cannot be resumed; create a new verification.no
provider_unavailable503The identity-verification provider is unavailable or not configured.yes
rate_limited429The journey anti-fraud rate limit was reached. Wait for the applicable window and retry.no
reference_already_consumed409Another proof was already consumed for this tenant, purpose and referenceId.no
reference_image_required400The verification was created with referenceMatch: image; send referenceImage (base64 JPEG/PNG) in /facetec/process.no
same_actor422The person who proposes the approval cannot be the one who accepts it, except solo: true when the approver is admin_super.no
verification_expired410The verification link expired or the journey already ended.no
verification_method_mismatch409The route does not apply to this verification’s method: /facetec/* requires facetec_sdk; the hosted page requires link.no
verification_not_consumable409The verification is not approved/fresh or is not bound to the supplied purpose and referenceId.no
verification_not_found404The verification does not exist in this tenant. IDs owned by another tenant return the same 404.no
verification_not_pending409The verification has already reached a terminal state.no
weak_pin422PIN outside the policy (6–12 digits, no repetition, sequence, short pattern or birth date).no
workflow_unavailable503The durable identity-verification workflow could not be started.yes

Account opening

CodeHTTPWhat happened and what to doRetryable
administrator_required422Opening a company with centralized biometry requires exactly one partner with isAdministrator: true. That person completes the capture.no
biometry_not_accepted422This tenant does not accept a biometry object on account opening. Capture uses the link in persons[].biometryLink or POST /v1/accreditations/{id}/capture.no
capture_call_limit429This link reached the maximum number of capture calls. Issue a new link.no
capture_expired410The capture link expired. Request another with POST /v1/accreditations/{id}/capture or the person retry.no
capture_failed_limit422Biometry was rejected too many times on this link. Issue a new link.no
capture_in_progress409A capture call is already in progress for this link. Wait for it to finish and try again.yes
capture_not_available409Capture is only available while the accreditation is PENDING_BIOMETRY and the verification has been opened.no
document_body_required422With centralized biometry, the company PDF goes in contentBase64. There is no upload URL.no
document_not_accepted422The biometry provider refused the document: file type not accepted or verification already closed.no
documents_incomplete409Approving a PJ without the required PDFs in the archive (object with size > 0). Use forceIncompleteDocuments + reason for an audited override.no
dracma_not_configured422The tenant has no active Dracma credential. Account opening with provider=dracma reads the verification with that credential; the CorpX global key is not a substitute.no
dracma_unavailable503Dracma did not respond in time. The verification was not accepted: a network failure does not approve biometrics. Try again.yes
evidence_not_found422The biometry.evidenceId does not exist (or does not belong to your tenant). Only applies to external biometrics flows enabled on request; contact support.no
feature_disabled403The accreditation (BaaS) feature is not enabled for your tenant. Contact CorpX to enable it. (Reads remain available.)no
file_too_large413Company PDF above 50 MB.no
invalid_callback_uri400The callbackUri you sent is not registered for your tenant, or is not accepted (only https:// and an application scheme; no credentials in the URI, no #, no localhost or internal network address). Register it under Identity verifications in the panel when that API is enabled, or ask CorpX support. The comparison is exact. See Returning to your app.no
invalid_content_type422contentType must be application/pdf for company document uploads.no
invalid_document400Document has an unexpected digit count (CPF=11, CNPJ=14).no
invalid_document_type400Invalid documentType — use CPF or CNPJ.no
invalid_kind422Invalid company document kind. Accepted: company_articles, company_proof_of_address, cnpj_card, financial_statements, business_license, regulatory_license, other.no
invalid_status409Company document upload blocked for the current status (only PENDING_BIOMETRY / BIOMETRY_APPROVED / PENDING_REVIEW).no
kyc_not_configured503Centralized biometry is enabled for this tenant, but neither the tenant nor CorpX has an account configured at the provider.no
kyc_upstream502The biometry provider did not complete this step. You can try again.yes
mixed_biometry_mode422PJ: all partners must use the same biometry mode. Dracma does not mix with the default flow or with another provider.no
not_pj422Company document upload is only accepted on PJ accreditations (POST .../documents).no
presign_error500Failed to generate the upload link for the evidence or corporate document. Safe to retry.no
provider_not_enabled422The given external biometry provider is not enabled for your tenant. Contact support.no
review_in_kyc_provider409Review of this opening happens at the biometry provider. Approving or rejecting it here does not apply.no
storage_unavailable503KYC archive (evidence bucket) temporarily unavailable.no
too_many_files422More than 10 kind=other files on the same accreditation.no
unsupported_provider422Unrecognized external biometry provider.no
verification_already_used409This verification id is already bound to another account opening that has not failed. Each id approves one journey.no
verification_cpf_mismatch422The CPF in the verification subject.cpf is not the person’s (holder or partner), or the response had no CPF. Without the 11 digits the id identifies no one.no
verification_not_approved422The Dracma verification is not approved. pending and review_required do not open an account.no
workflow_signal_failed502Failed to signal the accreditation workflow; retry.no

Boleto Charge

Issuing and consulting boletos of the account itself (Boleto Charge). Distinct from Boleto Pay, which pays someone else’s boleto.

CodeHTTPWhat happened and what to doRetryable
boleto_charge_account_disabled403Boleto issuance is not enabled for this account. boletoCharge.enabled=true on the tenant policy enables every account; on the account policy, only that account. The tenant boleto_charge feature must also be on.no
boleto_charge_account_holder_not_found422The settlement bank does not recognize this account holder in the boleto module. This is not a missing beneficiary: the holder must exist there before registration.no
boleto_charge_batch_chunk_invalid400Each batch upload must contain between 1 and 50 boletos.no
boleto_charge_batch_empty409The batch has no items to dispatch.no
boleto_charge_batch_item_conflict409The identifier already exists in the batch with another payload.no
boleto_charge_batch_item_not_found404Batch item not found.no
boleto_charge_batch_not_editable409Only a DRAFT batch accepts item changes.no
boleto_charge_batch_not_found404Boleto Charge batch not found in this account.no
boleto_charge_batch_too_large400A batch accepts at most 5,000 boletos.no
boleto_charge_beneficiary_not_found404This account has no boleto beneficiary yet. Registration or the first issuance registers the holder and returns 202 boleto_charge_beneficiary_pending.no
boleto_charge_beneficiary_registration_failed502The settlement bank rejected beneficiary registration, synchronously or by webhook in the last 24 hours. The message carries the reason; on a recent rejection, details.lastEvent carries rejectionCode and rejectionReason, and the Retry-After header carries the seconds until issuance registers again on its own. Retrying issuance before that does not help: fix the account data and register again with POST .../boleto/charge/beneficiary, which does not wait. Nothing was issued.no
boleto_charge_beneficiary_transition_invalid409The requested eligibility is not a valid transition from the current status. eligible goes to underReview or ineligible; underReview goes to eligible or ineligible; ineligible only returns to underReview.no
boleto_charge_issuance_in_progress409An issuance is already in progress for this identifier.yes
boleto_charge_issuance_outcome_unknown409The previous attempt may have reached the settlement bank, but its outcome was not confirmed. Do not retry automatically.no
boleto_charge_monthly_limit_exceeded429The issuance does not fit the tenant or account remaining monthly quota. Reservation is atomic and no batch item was started.no
commercial_policy_staff_required403Boleto Charge and identity-verification commercial quotas can only be changed by CorpX staff.no
invalid_batch_item422A batch item violates issuance rules; the message identifies its index.no
invalid_boleto_charge_policy400boletoCharge.enabled must be a boolean and boletoCharge.maxIssuesPerMonth, when present, an integer from 1 to 1000000. Unlimited mode is not supported.no
quota_unavailable503The monthly quota could not be read or reserved right now.yes

Balance holds

Hold part of the balance, release it to another CorpX account, or cancel it.

CodeHTTPWhat happened and what to doRetryable
account_locked_for_holds403The account has an active outflow lock (block, hours or source IP), and it applies to holding and releasing balance. Cancelling a hold is still allowed.no
hold_managed_by_order409This hold belongs to a P2P order. Only the order releases or cancels it; use the order routes.no
hold_not_active409The hold is not active: it was already released, cancelled, or is being released under another Idempotency-Key. Read the hold to see its state.no
hold_not_found404There is no hold with this holdId on this account.no
insufficient_available_balance422The account’s available balance is lower than the hold amount. Nothing was held. Check availableAmount on GET /balance.no
release_exceeds_hold422amount plus fee.amount must equal the total hold amount. Partial release does not exist: cancel and create another hold.no
release_failed422The release transfer was refused and the amount is held again (active). details.cause carries the reason. Fix it and release again with another Idempotency-Key.no

P2P Crypto

P2P stablecoin market: profiles, wallets, ads, orders, signing and disputes.

CodeHTTPWhat happened and what to doRetryable
ad_closed409The ad was closed and cannot be edited again. Create another one.no
ad_not_found404There is no ad with this adId in the market.no
ad_suspended422The ad was suspended by CorpX and only CorpX can reactivate it. It can be edited or closed, but not turned back on.no
ad_unavailable409The ad does not accept orders right now: it is paused, has no stock for the amount, has no quote, its pair is disabled, its advertiser is not approved, its wallet is not cleared, or the advertiser’s tenant left the market. Nothing was locked. List the market again.no
advertiser_not_approved403Only an approved advertiser creates or reactivates ads. Request approval with POST /p2p/advertiser-requests.no
advertiser_request_not_allowed409An advertiser request is already under review, or the account is already an advertiser, or it was suspended.no
amount_above_cap422The amount exceeds a cap: per order (the lowest among the market’s and the two parties’ tenants’), the advertiser’s per-order cap, or the buyer’s daily cap (day in Brasília time). The message says which.no
amount_out_of_ad_limits422The order amount is outside the ad’s minimum and maximum. The message carries the accepted range.no
contact_already_verified409This P2P profile channel is already confirmed.no
contact_code_invalid422The contact confirmation code is invalid or expired.no
contact_code_locked422Too many code attempts. Request a new code.no
contact_code_rate_limited429Too many codes sent for this contact. Wait before requesting another.no
contact_delivery_failed503The confirmation code could not be sent right now. Try resending.no
contract_not_available409This party’s signed copy does not exist yet: signing has not finished or is disabled in the market.no
delivery_deadline_out_of_range422deliveryDeadlineMin is outside the market’s range. The message carries the range.no
dispute_already_decided409The dispute was already decided; it no longer accepts messages or evidence.no
dispute_already_open409A dispute is already open on this order.no
dispute_not_allowed_yet409A dispute is not allowed yet: the buyer disputes after the delivery deadline; the seller, 60 minutes after sending or 24 hours after on-chain confirmation.no
dispute_not_found404This order has no dispute.no
hold_lock_unknown503The bank did not confirm the balance lock. The order was not opened and CorpX reconciles the balance; do not repeat the order before checking the balance.no
holder_only403Only the account holder performs this operation. The document in X-Acting-Document belongs to someone else.no
holds_unavailable503The balance hold service is unavailable. The order was not opened.no
invalid_network422The wallet network is not accepted. Check the networks on GET /p2p/pairs.no
invalid_offset422offset must stay within 5% of the current Binance spot (the same cap as 500 bps). The message carries the limit in BRL, with 4 decimal places.no
invalid_spread422spreadBps must be between -500 and 500.no
invalid_username422username accepts 3 to 24 characters: lowercase letters, digits, _ and ..no
invalid_wallet_address422The address is not valid for the given network.no
order_not_cancellable409The order can no longer be cancelled: both parties signed the contract or it has ended.no
order_not_concluded409The receipt is only issued once the trade is concluded: released, signed by both parties, seller paid and fee charged.no
order_not_found404There is no order with this orderId in which this account is a party.no
order_role_not_allowed403This step belongs to the other party: the seller reports the txid and the buyer releases the amount.no
order_step_out_of_order409The order is not at the step this call requires. Read the order to see its status.no
order_unavailable503The order could not be opened due to a temporary failure. Nothing stayed locked; retry with another Idempotency-Key.no
p2p_contact_unverified422The P2P profile e-mail or phone is not confirmed yet. Confirm both before advertising or trading.no
pair_not_enabled422The pair (crypto and network) is not enabled in the market.no
price_evidence_not_found404The order exists but has no recorded quote evidence. Only happens for orders opened before evidence recording was introduced.no
price_unavailable409Binance did not return the spot price at opening time (timeout, HTTP error, rate limit or invalid response). Opening requires this lookup, even for fixed-price ads, because the quote at that moment is recorded as evidence. No order was created and nothing was locked. Retry shortly with the same Idempotency-Key.no
profile_not_found404There is no public P2P profile with this username.no
screening_unavailable503Wallet risk screening is unavailable. The order was not opened; retry shortly.no
self_trade409The account tried to trade against its own ad or against an ad from another account of the same holder.no
signer_contact_missing422The P2P profile does not have a confirmed e-mail and phone to sign the contract. The order was not opened; confirm the contact on the P2P profile before trading.no
stock_below_reserved422Stock cannot go below what is already reserved in open orders.no
term_not_available409The consolidation term does not exist yet: the trade has not concluded or the PDF has not been generated.no
txid_already_used409This txid was already reported on another order.no
txid_invalid_format422The txid does not match the pair’s network format (Tron: 64 hexadecimal characters).no
txid_limit_reached422The order already received the maximum number of txids. Open a dispute if the transfer does not show up.no
username_change_too_soon409The username was already changed in the last 90 days. Creating the profile does not count; each change starts a 90-day cooldown. details.nextChangeAt carries the date from which a change is accepted again.no
username_required409Set the P2P profile username before requesting to advertise.no
username_taken409Another profile in the market already uses this username. The username is unique across every tenant.no
wallet_already_registered409This wallet is already registered on this account.no
wallet_in_open_order409The wallet is in an ongoing order or is the wallet of an active ad. Wait for the order to finish or change the ad’s wallet.no
wallet_not_approved422The wallet did not pass risk screening or is still under review. On order opening, details.walletOf says whose wallet was refused (taker or maker).no
wallet_not_found404There is no wallet with this walletId on this account.no