Errors

All error responses share this envelope:

{
  "status": "error",
  "error": {
    "code":    "RMT-XXXX",
    "field":   "<field-if-applicable>",
    "message": "Human-readable description"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

The code is stable across versions and safe to switch on programmatically. The message is human-friendly and may change over time — do not switch on it. The field is present when the error is attached to a specific request field.

RMT-1xxx — validation

Code	HTTP	Meaning
RMT-1005	400	Required field missing. field names which field.
RMT-1010	400	Name too short / abbreviated / contains . or *. Full legal names only.
RMT-1013	400	Cash pickup (operator=fbnbank) requires receiver_document_type and receiver_document_number.
RMT-1014	400	receiver_document_type is not one of the accepted enum values.
RMT-1015	400	sender_document_type is not one of the accepted enum values.
RMT-1016	400	reason_of_transaction is not one of the accepted enum values.
RMT-1017	400	source_of_funds is not one of the accepted enum values.
RMT-1018	400	Both receiver_current_address and receiver_permanent_address missing. At least one is required.

RMT-2xxx — auth

Code	HTTP	Meaning
RMT-2001	401	Missing or malformed Authorization header.
RMT-2002	401	Invalid merchant_code or merchant_secret.
RMT-2003	403	Merchant account is not active. Contact support.
RMT-2004	403	IP not in whitelist for this merchant.

RMT-3xxx — wallet & pricing

Code	HTTP	Meaning
RMT-3001	402	Insufficient wallet balance for the requested amount + fee.
RMT-3002	409	Duplicate reference — this reference was already used.
RMT-3003	404	No wallet for this merchant + operator + currency + direction.

RMT-4xxx — compliance

Code	HTTP	Meaning
RMT-4001	403	Sender or receiver appears on sanctions list (blocked).
RMT-4002	403	Prohibited corridor combination.
RMT-4006	422	Receiver name mismatch — declared name does not match telco record. Response includes expected, telco and score.

RMT-5xxx — telco / downstream

Code	HTTP	Meaning
RMT-5001	502	Telco returned an error we don't recognize.
RMT-5002	400	Bad format on downstream call — check `format=pdf
RMT-5003	502	Telco temporarily unavailable. Retry after ~30s.

RMT-9xxx — service-level

Code	HTTP	Meaning
RMT-9001	403	Endpoint currently disabled (e.g. /outbound).
RMT-9002	403	Operator not enabled for your account.
RMT-9003	403	Sandbox amount cap (1 USD per transaction) exceeded. Go Live to lift.

Retry guidance

• RMT-1xxx, RMT-4xxx: do not retry. Fix the payload and re-submit.
• RMT-2xxx: fix auth first. Retrying with the same credentials fails.
• RMT-3001, RMT-3003: do not retry. Top up your wallet from the dashboard.
• RMT-3002 (duplicate reference): the previous call succeeded; use /transaction/status to fetch the outcome.
• RMT-5003: retry with exponential backoff, up to 3 attempts.
• Any other 5xx: retry once after 5 seconds, then escalate to support.