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

CategoryHTTP rangeStrategy
Validation errors400Fix the payload and retry only after correction.
Business/compliance errors400, 403Require user action or compliance resolution before retrying.
Conflict errors409Do not retry: the state conflict will not resolve on retry.
Not found404Verify the ID; escalate if the resource should exist.
Rate limiting429Retry with exponential backoff. Wait the seconds given in the Retry-After header before the first retry. See Authentication.
Transient/server errors5xxRetry 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

internalStatusHTTPDescription
USER_EXISTS / USER_EXISTS_EMAIL409User already exists. Fetch the existing user.
EMAIL_EXISTS409Email already registered.
INVALID_CBU409Bank account (CBU) is invalid.
INACTIVE_ADDRESS409Bank account is not active.
COIN_MISMATCH400Bank account currency does not match the asset.
CUIT_MISMATCH400Bank 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:

internalStatusHTTPDescription
PERSON_MONTHLY_OPERATION_LIMIT403The purchase would exceed the company's monthly USD cap.
PERSON_YEARLY_OPERATION_LIMIT403The purchase would exceed the company's yearly USD cap.

See Onboarding a company → Operating as a company.


Documentation error codes

internalStatusHTTPDescription
INVALID_DOCUMENTATION_FORMAT409Unsupported document format.
DOCUMENTATION_PENDING409Document exists and is pending validation.
DOCUMENTATION_EXISTS409Document already exists and is valid.
ONBOARDING_PENDING409Complete personal data before uploading documents.
PERSON_NF404No 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 externalId on 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.


Did this page help you?