Error Codes

When a request fails, Settlra returns a JSON body with an error code, a human-readable message, and optionally a details object with field-level validation errors.

Error response format

{
  "error": "QUOTE_EXPIRED",
  "message": "This quote has expired. Please create a new quote.",
  "details": {}
}

All error codes

Code	HTTP	Description	What to do
`QUOTE_NOT_FOUND`	404	No quote with the given ID exists for your account.	Verify the quote_id. Ensure it was created by the same API key.
`QUOTE_EXPIRED`	410	The quote has passed its 5-minute expiry window.	Create a new quote and retry immediately.
`QUOTE_ALREADY_USED`	409	The quote has already been used to create a payout.	Each quote can only be used once. Create a new quote.
`INSUFFICIENT_FLOAT`	503	Settlra's liquidity pool for the requested corridor is temporarily low.	Retry in a few minutes. Contact support if this persists.
`KYC_REQUIRED`	403	Account KYC has not been approved, or tier is insufficient for this transaction.	Complete KYC verification in the dashboard.
`DAILY_LIMIT_EXCEEDED`	403	The requested amount would exceed your daily payout limit for your KYC tier.	Wait until the daily window resets (midnight UTC), or upgrade your KYC tier.
`MONTHLY_LIMIT_EXCEEDED`	403	The requested amount would exceed your monthly payout limit.	Upgrade your KYC tier or contact support for a custom limit.
`PER_TRANSACTION_LIMIT_EXCEEDED`	403	The individual payout amount exceeds the per-transaction limit for your KYC tier.	Split into smaller payouts, or upgrade your KYC tier.
`COMPLIANCE_BLOCK`	403	The recipient or transaction was flagged by AML or sanctions screening.	Contact support. Do not retry without resolution.
`INVALID_RECIPIENT`	422	The recipient phone number is not a valid, active mobile money account on the specified network.	Verify the phone number format (E.164) and that the number is registered on the network.
`DUPLICATE_IDEMPOTENCY_KEY`	409	An idempotency key was reused with different request parameters.	Use a different idempotency key, or use the same key with identical parameters to retrieve the original response.
`PAYOUT_NOT_FOUND`	404	No payout with the given ID exists for your account.	Verify the payout_id. Ensure it was created by the same API key.
`PROVIDER_ERROR`	502	The downstream mobile money provider returned an error.	The payout will be retried automatically. You can also check status via GET /v1/payouts/:id.
`INTERNAL_ERROR`	500	An unexpected error occurred on Settlra's servers.	Retry with exponential backoff. Contact support with the request ID if it persists.
`RATE_LIMIT_EXCEEDED`	429	Too many requests from this API key in the current time window.	Slow down your request rate. Check X-RateLimit-Reset for when the window resets.
`VALIDATION_ERROR`	400	One or more request parameters are missing or malformed.	Check the details field in the response for specific validation errors.

KYC tier limits

Limit-related errors (DAILY_LIMIT_EXCEEDED, etc.) depend on your account's KYC tier:

Tier	Per transaction	Daily limit	Monthly limit
`TIER_1`	$500	$2,000	$10,000
`TIER_2`	$10,000	$25,000	$150,000
`ENTERPRISE`	Custom	Custom	Custom

To increase your limits, complete the KYC verification process for TIER_2, or contact us for enterprise limits.