Error Handling

HTTP Status Codes

Code	Description
200	Success
202	Accepted — pending approval (antifraud)
400	Bad Request — invalid or missing parameters
401	Unauthorized — invalid or expired token
402	Payment Required — tenant suspended/restricted by billing (ACCOUNT_SUSPENDED / ACCOUNT_RESTRICTED)
403	Forbidden — access denied or blocked by antifraud
404	Not Found
405	Method Not Allowed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Response Formats

Most business/validation failures return a body with message and the corresponding HTTP status:

{
  "message": "Detailed error description"
}

Gateway-level errors (tenant validation, billing, antifraud) add a stable error identifier — use it for programmatic handling:

{
  "error": "MISSING_CLIENT_ID",
  "message": "Client ID (x-client-id) is required"
}

There is no proprietary E##### error-code catalogue — handle errors by HTTP status and, when present, the error field.

Gateway (tenant validation) Errors

HTTP	error	Cause	Solution
400	MISSING_CLIENT_ID	Tenant not identified — the Bearer token alone is not enough	Send x-client-id: <your Client_ID> on every call (details)
402	ACCOUNT_SUSPENDED / ACCOUNT_RESTRICTED	Tenant billing status blocks the operation	Settle outstanding invoices
403	PRODUCT_NOT_ENABLED	Product family (BANKING / CRYPTO / KYC / …) not enabled	Contact support
403	OPERATION_NOT_ALLOWED	Tenant restricted to a subset of operations (e.g. PIX only)	Contact support
403	TRANSACTION_BLOCKED	Blocked by antifraud	Contact support with the returned antifraudId
202	TRANSACTION_PENDING_APPROVAL	Held for manual antifraud approval (not an error)	Wait; response carries antifraudId and pendingExpiresAt

Common Errors

Error	Cause	Solution
Invalid token	Expired or revoked Bearer token	Re-authenticate via /access-token
Account not found	Invalid account ID or document	Verify account exists and is active
Insufficient funds	Account balance too low	Check balance before transfer
Duplicate transaction	Same Idempotency-Key reused	Use a new UUID
Rate limit exceeded	Too many requests	Implement exponential backoff
Tenant suspended	Billing issue on tenant	Contact support

---