Error Catalog - Dollr Developer Docs

HTTP status codes tell you what class of problem occurred. This catalog covers frequent **detail** messages and field validation patterns so you can fix requests without opening a support ticket. For step-by-step fixes, see the Knowledge Base. For retry logic and idempotency rules, see Error Handling.

Topic	Knowledge Base article
401 credentials	Invalid credentials
403 forbidden	Forbidden / unverified
422 validation	Validation errors
Idempotency	Duplicate reference_id
Sessions	Session expired
MoMo delays	PROCESSING status
429 rate limit	Rate limit
5xx server	Server errors

Authentication & authorization

Symptom	Typical HTTP	What it means	What to do
`Could not validate credentials`	`401`	Missing, malformed, or expired Bearer token	401 guide — refresh token before `expires_in` elapses
Token works on one endpoint but `403` on another	`403`	Account not verified or feature gated	403 guide
`Not authenticated`	`401`	No `Authorization` header	Send `Authorization: Bearer <access_token>` on every call

Validation (HTTP 422)

Inspect the detail array. Each item has loc, msg, and type.

Field / pattern	Example `msg`	Cause	Fix
`body.currency`	`field required`	Currency omitted	ISO 4217 uppercase, e.g. `USD`
`body.phone`	`invalid phone` / length errors	Not E.164 without `+`	Use digits only, e.g. `231771234567`
`body.reference_id`	`invalid uuid`	Not UUID v4	Generate with `uuid4()` once per execution attempt
`body.reference_id`	duplicate / already exists	Reused idempotency key for a different payment	Query status with the same `reference_id` first
`body.amount`	less than minimum	Below `0.01` or integer rules	Increase amount or use predictions endpoint
`body.session_id`	session not found / expired	Session timed out or wrong ID	Create a new session; do not reuse stale IDs
`body.payment_account_id`	not found	Account not registered for party	`POST /v1/payment-accounts/create?operation_type=COLLECTION`
`body.method` / `body.provider`	invalid combination	Mismatched MoMo operator	Call MMO provider prediction
`body.source_type` / `body.source_kind`	invalid enum	Wrong document type constant	Use `INVOICE` or `ORDER` for checkout sources (see Checkouts)
`body.counterparty_id`	required	Invoice/order without counterparty	Create Counterparty first in document-first flows

Resource state errors

Symptom	HTTP	Cause	Fix
Invoice not publishable	`422` / `404`	Still `IDLE` or wrong ID	`PUT /v1/invoices/publish/{id}` when ready
Execution rejected — session	`422`	Session not `ACTIVE` or wrong operation type	Match session type to execution (`checkout` → `collection`)
Source `CANCELED`	`422`	Invoice/order canceled	Create a new source; do not execute against canceled IDs
Party / counterparty mismatch	`422`	IDs from another merchant	Use IDs returned under your authenticated merchant

Execution & status

Symptom	HTTP	Cause	Fix
Status stays `PROCESSING`	`200` on status poll	MoMo carrier delay (normal)	PROCESSING guide — do not retry with a new `reference_id`
Status `FAILED`	`200`	Payer declined, insufficient funds, or operator error	Show failure to user; optional new session + new `reference_id` for a new attempt
Lost HTTP response after execute	—	Network timeout	Poll status with stored `reference_id` before retrying execute
`429 Too Many Requests`	`429`	Rate limit	Honor `Retry-After`; exponential backoff

Server errors (5xx)

Symptom	Action
`500` / `502` / `503`	Retry with backoff; if persistent, contact support with `reference_id` and timestamp
Intermittent timeouts on execute	Treat as ambiguous: status poll first, then retry only if status shows no `COMPLETED`/`PROCESSING`

Support payload checklist

When escalating to Support or dev@heydollr.app, include:

reference_id (if execution-related)
Request URL, method, and redacted body
Full response status + JSON body
Merchant ID / environment (test vs live)
Payment method, provider, and market

Knowledge Base — detailed troubleshooting articles
Error Handling — retries, backoff, rules
Transaction Status — polling execution vs source status
Try in API Reference: collection status

Last modified on May 22, 2026