Errors and retries

A failed request returns status: false, an error message, and a stable code. Match on code, and display error to people.

{
  "status": false,
  "error": "Quote lapsed or already used. Get a new one.",
  "code": "quote_expired"
}

Error codes

A 404 response does not reveal whether another business owns the quote or order.

HTTP	Code	When
400	`bad_request`	Malformed JSON, a missing required field, or an invalid field format.
400	`amount_required`	Provide exactly one of `source_amount` or `destination_amount`.
400	`invalid_amount`	Quote amount is outside the supported range.
400	`invalid_currency`	Neither side is NGN, or both are.
400	`invalid_asset`	Unsupported crypto asset.
400	`invalid_network`	Unsupported chain for that asset.
400	`quote_expired`	Quote lapsed or already used. Get a new one.
409	`quote_not_refreshable`	A consumed quote cannot be refreshed.
400	`quote_flow_mismatch`	Onramp quote used on offramp, or the reverse.
400	`invalid_destination_address`	Not a valid address for the chain.
400	`account_verification_failed`	Bank could not confirm the account.
401	`unauthorized`	Invalid or missing API key.
404	`quote_not_found`	No such quote for your business.
404	`order_not_found`	No such order for your business.
409	`duplicate_reference`	The reference belongs to a different request in the same resource.
409	`quote_changed`	A refresh changed the quote during order creation.
429	`rate_limited`	Too many requests. Wait 60 seconds before retrying.
503	`service_unavailable`	An upstream service was unreachable and nothing was written. Retry.
500	`internal`	Unexpected failure. Safe to retry with the same reference.

An order create can time out after Pulse stores the order. The reference lets a repeated request return that order instead of creating another one.

Generate a reference for the payment in your system. Store it before you create the order.

After a timeout, 503 service_unavailable, or 500 internal, send the same body with the same reference.

After a successful create, store the returned order ID (id) with your reference. You can also find the order with GET /v1/orders?reference=....

Use a unique reference for each order across both flows. Reuse a reference only for the same create request.

For 409 duplicate_reference, read the existing order. Use a new reference only when you intend to create a different order.

For 409 quote_changed, your integration must refresh the quote again and review the response. It can then retry the order request.