Errors | CorpX API

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.

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.

Code	HTTP	What happened and what to do	Retryable
`account_not_found`	404	The `accountId` in the path does not exist.	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
`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
`method_not_allowed`	405	The HTTP method is not accepted on this route. Check the method in the API reference.	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
`rate_check_unavailable`	503	Could not validate the journey rate limit right now. Retry in a moment.	no
`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.

Code	HTTP	What happened and what to do	Retryable
`account_not_entitled`	409	The 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_ready`	409	The 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_partner`	409	The document is already accredited at the banking provider by another participant. Requires a control transfer through support.	no
`bacen_rejected_content`	400	Text content (description/message) contains a character the Brazilian Central Bank does not accept.	no
`balance_reservation_failed`	422	Balance reservation failed (funds locked, settling, or racing with another operation).	no
`boleto_already_settled`	409	The bank slip is already settled. Check the original payment before resending.	no
`boleto_amount_mismatch`	422	Amount differs from the registered bank slip amount (consider interest, fine and discount).	no
`boleto_scheduled`	409	There is an active schedule for the same barcode.	no
`challenge_failure`	422	PIN/2FA validation failed at the banking provider.	no
`conflict`	409	State conflict at the banking provider (e.g. resource already processed).	no
`identifier_conflict`	409	The `Identifier` was already used at the banking provider. Resending the same value does not create a new operation.	no
`insufficient_funds`	422	Insufficient balance as computed by the banking provider at settlement time.	no
`invalid_field`	400	Field-level validation at the banking provider. `partner.field` names the field and the message carries the limit when available.	no
`invalid_payload`	400	The banking provider rejected the request body. The `partner` block carries the original validation message.	no
`invalid_pix_key`	400	Key format does not match the declared type (`CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`).	no
`key_inactive`	422	The key exists but is inactive or under portability. Use another key or bank details.	no
`key_not_found`	404	Key not found in DICT. Check for typos or ask the recipient for another key.	no
`key_ownership_mismatch`	422	Attempt to register or use a key whose document differs from the account holder’s.	no
`limit_exceeded`	422	A limit was exceeded but the provider did not say which window.	no
`limit_exceeded_daily`	422	For 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_monthly`	422	Accumulated monthly limit. Only clears at month rollover or with a limit increase.	no
`limit_exceeded_nightly`	422	Nighttime window limit (20:00–06:00), usually lower than the daytime one.	no
`limit_exceeded_transaction`	422	Per-transaction limit. Split the operation or request a limit increase.	no
`not_found`	404	Resource does not exist at the banking provider (id, key or transaction).	no
`not_supported`	501	The 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_supported`	400	Legacy — no longer returned: partial refunds are now accepted. An amount above the original returns `refund_amount_exceeded`.	no
`partner_account_disabled`	422	Source account is disabled at the banking provider (reactivation required).	no
`partner_error`	502	Unclassified failure while talking to the banking provider. Safe to retry.	yes
`partner_forbidden`	502	Operation blocked by the banking provider for this account (product or permission not enabled).	no
`partner_internal`	502	Internal (5xx) error at the banking provider. Safe to retry.	yes
`partner_rate_limited`	429	The banking provider throttled CorpX’s traffic. Nothing is wrong with your request — slow down and retry with backoff.	yes
`partner_rejected`	422	Refused by the banking provider on internal policy, risk or fraud grounds. The `partner` block carries the stated reason.	no
`partner_unauthorized`	502	CorpX’s own credential at the banking provider was rejected. Not related to your credential; wait a few minutes before resending.	no
`partner_unavailable`	502	Provider outage or gateway failure. Safe to retry.	yes
`pix_key_limit_exceeded`	422	Maximum number of keys per account reached (5 for individuals, 20 for companies).	no
`qr_amount_mismatch`	422	A fixed-amount QR Code does not accept a different amount.	no
`qr_gone`	409	QR Code removed or expired at the banking provider.	no
`recipient_account_not_found`	422	Destination bank/branch/account does not exist. Applies to TED and internal transfers.	no
`refund_amount_exceeded`	400	Refund amount is larger than the refundable balance of the original PIX.	no
`timeout`	504	Timeout calling the banking provider. The operation may exist — query it before resending.	yes

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 or uses disallowed characters.	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

QR Code

Code	HTTP	What happened and what to do	Retryable
`missing_field`	400	`pixKey` missing — and, on dynamic QR, `value` missing or not positive.	no
`missing_param`	400	Lookup and cancellation require the `identifier` query param (alias `txid`).	no

PIX keys

Code	HTTP	What happened and what to do	Retryable
`key_type_temporarily_unavailable`	422	Registering an `email` or `phone` key is temporarily unavailable. Use `cpf`, `cnpj`, or `random`. Listing and deleting those key types still works.	no

Refund

Code	HTTP	What happened and what to do	Retryable
`original_transaction_not_found`	404	The original transaction (`originalEndToEnd`) was not found.	no

TED

Code	HTTP	What happened and what to do	Retryable
`invalid_account_type`	400	`accountType` must be `CHECKING`, `SAVINGS`, `PAYMENT` or `SALARY`. Omitted, it defaults to `CHECKING`.	no
`invalid_tax_number`	400	`taxNumber` must have 11 (CPF) or 14 (CNPJ) digits.	no
`missing_fields`	400	Missing `value`, `holderName`, `branch`, or `account`.	no

Internal transfer

Code	HTTP	What happened and what to do	Retryable
`multiple_destination_accounts`	409	On `/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

Code	HTTP	What happened and what to do	Retryable
`bucket_mismatch`	409	The export file was produced in another environment and cannot be downloaded here. Create the export again.	no
`date_range_too_wide`	400	The statement window exceeds 31 days. Split it into smaller periods.	no
`invalid_cursor`	400	The pagination `cursor` is invalid or belongs to another query. Start over without `cursor`.	no
`invalid_date_range`	400	`startDate` / `endDate` outside the `YYYY-MM-DD` format.	no
`invalid_filter`	400	Invalid advanced statement filter (`type`, `direction`, `status`, `minAmount`/`maxAmount` or dates). The message names the field.	no
`invalid_format`	400	Export `format` must be `csv`, `pdf`, or `xlsx`.	no
`invalid_operation`	400	The entry detail requires the `operation` query param: `PIX`, `TED`, `BOLETO`, `INTERNAL`, or `FEE`.	no
`invalid_query`	400	The per-account timeline requires exactly one of `endToEndId` and `identifier` — never both, never neither.	no
`invalid_s3_key`	500	Internal reference to the export file is invalid. Create the export again; if it persists, contact support.	yes
`missing_account_id`	400	`accountId` missing from the path. Use `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...`.	no
`missing_identifier`	400	Pass `identifier` or `endToEnd` in the query to locate the payment.	no
`not_ready`	409	Download requested before the export finished. Poll the status until `completed`.	no
`presign_failed`	500	Failed to generate the download link for an already finished file. Safe to retry.	no

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)

Code	HTTP	What happened and what to do	Retryable
`body_hash_mismatch`	400	The received body does not match the signed `X-Content-SHA256`.	no
`credential_not_yet_active`	403	Freshly issued credential still inside its grace period. Wait for the `activeFrom` returned at issue time.	no
`invalid_ip`	400	Invalid address or CIDR in the IP allowlist. Use IPv4/IPv6 or CIDR notation (`203.0.113.10/32`).	no
`invalid_public_key`	422	The 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_derived`	409	The tenant has delegated credentials: its IP allowlist is derived from them and does not accept manual edits.	no
`ip_allowlist_required`	422	`allowedIps` missing, empty, longer than 20 entries, containing `0.0.0.0/0` or a prefix wider than `/24`.	no
`ip_not_allowed`	403	The request came from an IP outside the credential’s allowlist.	no
`last_public_key`	409	The credential’s last usable key cannot be retired.	no
`public_key_limit_reached`	409	Public key limit per credential reached. Retire one before adding another.	no
`public_key_required`	422	Issuing a delegated credential requires `publicKeyPem`.	no
`request_signature_invalid`	403	The 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_required`	403	Missing `X-Request-Signature`, `X-Request-Timestamp` or `X-Content-SHA256`.	no
`request_timestamp_skew`	403	`X-Request-Timestamp` outside the 300s window. Sync the server clock (NTP).	no
`scope_not_delegable`	403	The scope requested for the child credential is not held by the delegating credential, or is not delegable.	no
`signature_required`	403	The request reached `client.api.corpx.com` without the signature headers. Edge block, before the token is looked at.	no
`signed_host_required`	403	A delegated credential was used on `tenant.api.corpx.com`. Retry on `client.api.corpx.com`, signed.	no
`unknown_kid`	403	The `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)

Code	HTTP	What happened and what to do	Retryable
`acting_document_required`	400	Send `X-Acting-Document` (the operator’s CPF) together with the PIN.	no
`cashout_locked`	423	The account holder blocked money from leaving this account (`cashoutBlocked`).	no
`cashout_outside_hours`	403	Outside the time window configured by the account holder. The message states the window.	no
`cashout_source_ip_not_allowed`	403	The operation’s source IP is outside `cashoutSourceIps`. Integrators must pass the end user’s real IP in `X-Acting-Ip`.	no
`credential_not_found`	404	The `clientId` in the path does not exist in this tenant.	no
`hash_error`	500	Internal failure while protecting the PIN. Retry; if it persists, contact support.	yes
`invalid_cashout_hours`	422	`cashoutHours` with an invalid `HH:MM`, `start` equal to `end`, or an unknown timezone.	no
`limits_unavailable`	503	The limits service did not respond. Retry shortly.	yes
`no_pending_change`	404	There is no scheduled loosening to cancel or bring forward.	no
`pin_invalid`	403	Wrong PIN. The attempt was counted.	no
`pin_locked`	423	6 wrong attempts: unlocking requires resetting the PIN.	no
`pin_not_found`	404	No PIN registered for the given operator.	no
`pin_not_set`	403	This operator has no PIN registered on this account.	no
`pin_required`	428	The credential requires `X-Acting-Document` and `X-Transaction-Pin` on cashout operations.	no
`pin_temporarily_locked`	429	3 wrong attempts: locked for 15 minutes. The `Retry-After` header carries the seconds.	no
`weak_pin`	422	PIN outside the policy (6–12 digits, no repetition, sequence, short pattern or birth date).	no