Errors and Controls
Broker errors carry an internalStatus (a stable verbal code) and a message (detail). Use internalStatus as the key for programmatic handling, not the HTTP status alone.
Retry guidance by error category
| Category | HTTP range | Strategy |
|---|---|---|
| Validation errors | 400 | Fix the payload and retry only after correction. |
| Business/compliance errors | 400, 403 | Require user action or compliance resolution before retrying. |
| Conflict errors | 409 | Do not retry: the state conflict will not resolve on retry. |
| Not found | 404 | Verify the ID; escalate if the resource should exist. |
| Rate limiting | 429 | Retry with exponential backoff. Wait the seconds given in the Retry-After header before the first retry. See Authentication. |
| Transient/server errors | 5xx | Retry with exponential backoff, using externalId for idempotency. |
Do not retry on 409. A conflict means the operation is blocked by current state (duplicate operations, validation requirements, or active limits) and will return the same error until the underlying state changes.
User creation error codes
internalStatus | HTTP | Description |
|---|---|---|
USER_EXISTS / USER_EXISTS_EMAIL | 409 | User already exists. Fetch the existing user. |
EMAIL_EXISTS | 409 | Email already registered. |
INVALID_CBU | 409 | Bank account (CBU) is invalid. |
INACTIVE_ADDRESS | 409 | Bank account is not active. |
COIN_MISMATCH | 400 | Bank account currency does not match the asset. |
CUIT_MISMATCH | 400 | Bank account tax ID differs from the user's. |
Order creation error codes
See Orders for the full table. The most common are NO_FUNDS (400), BANK_HOLIDAY (400), INVALID_ASSET (400), PERSON_DEPOSIT_LIMIT (403), and ORDER_EXISTS (409).
A Dólar MEP purchase by a company can also be rejected for its operation caps:
internalStatus | HTTP | Description |
|---|---|---|
PERSON_MONTHLY_OPERATION_LIMIT | 403 | The purchase would exceed the company's monthly USD cap. |
PERSON_YEARLY_OPERATION_LIMIT | 403 | The purchase would exceed the company's yearly USD cap. |
See Onboarding a company → Operating as a company.
Documentation error codes
internalStatus | HTTP | Description |
|---|---|---|
INVALID_DOCUMENTATION_FORMAT | 409 | Unsupported document format. |
DOCUMENTATION_PENDING | 409 | Document exists and is pending validation. |
DOCUMENTATION_EXISTS | 409 | Document already exists and is valid. |
ONBOARDING_PENDING | 409 | Complete personal data before uploading documents. |
PERSON_NF | 404 | No person linked to that tax ID. |
Idempotency with externalId
Orders, withdrawals, and other operations accept an optional externalId (your reference). On a retry of an already-succeeded request, the API returns a duplicate error (for example ORDER_EXISTS, 409) instead of creating a duplicate. On that conflict, fetch the existing resource and use its current state. A retry sent while the first request is still being processed returns DUPLICATE_REQUEST (400): wait and fetch the resource by externalId.
Recommended controls
- Set
externalIdon every operation creation call. - Persist operation IDs and statuses in your own database at creation time.
- Build webhook handlers as idempotent consumers.
- Reconcile periodically using the list endpoints and
GET /broker/v1/api/accounting/summary.
For endpoint-level behavior, see the API Reference.
Updated 22 days ago