Error codes

Every API error returns the same envelope:

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

HTTP code	Meaning
400	Malformed request (invalid header, invalid JSON)
401	Authentication (missing, invalid or revoked key)
403	Authorisation (insufficient scope)
404	Resource not found for this merchant
409	Conflict (idempotency mismatch, request in flight)
422	Business validation (limit exceeded, inconsistent state)
429	Rate limit
500	Internal error (report it to support)
502	Orange Money unavailable upstream

Full list

Authentication

• missing_credentials — no Authorization header
• invalid_api_key — unknown, revoked or expired key, or IP outside the allowlist
• scope_insufficient — key without the scope this route requires (e.g. can_refund for POST /v1/refunds)

Request signing (optional)

See Authentication → Request signing.

• invalid_timestamp (400) — Soamtar-Timestamp more than 300 s away from SOAMTAR's clock
• invalid_signature — Soamtar-Signature does not start with v1= (400), or does not match when strict enforcement is on (401)

Idempotency

• idempotency_key_too_long — more than 255 characters
• idempotency_conflict — same key with a different body, OR request still in flight

Payments

• payment_rejected — business validation (provider, currency, amount precision, limit, KYC)
• gateway_error — Orange Money refused to start the payment (502)
• transaction_not_found — id or reference unknown for this merchant (or created in the other mode)

Refunds

See Refunds.

• transaction_not_found (404) — payment id or reference unknown for this merchant
• refunds_disabled (422) — refunds are not enabled on your account
• refund_environment_mismatch (422) — test key on a live payment or the reverse
• transaction_not_refundable (422) — the payment is not success or partially_refunded
• non_payment_transaction_refund (422) — only payments can be refunded
• provider_refund_unsupported (422) — the payment method does not support refunds
• refund_payer_phone_missing (422) — the payment has no payer phone number to credit
• amount_must_be_positive (422) — amount is zero or negative
• transaction_already_fully_refunded (422) — nothing left to refund
• refund_exceeds_refundable (422) — amount above the remaining refundable amount
• refund_rejected (422) — the refund could not be created
• scope_insufficient (403) — the key lacks the can_refund scope
• refund_not_found (404) — unknown refund id or reference

Webhooks

• no_webhook_endpoints (400) — POST /v1/webhooks/test without any active endpoint

Payouts

• payout_not_allowed_in_test_mode — payouts need a live key (sk_live_…)

Splits

• split_rejected — total above the transaction amount, inactive beneficiary, terminal transaction

What to do

Code	Recommended action
4xx (validation)	Fix the request, use a new Idempotency-Key
401	Check the key. Do NOT retry.
409	Check your idempotency logic
429	Wait for Retry-After, then retry
5xx	Retry with the same Idempotency-Key, exponential backoff
502	Orange Money upstream — retry after a few seconds

Reporting a bug

Email support@so-amtar.com with:

• the error code
• the documentation_url
• the exact timestamp (UTC)
• your merchant_ref or the SOAMTAR id
• the response's X-Request-Id header (if present)