Statuses and errors - LightSwap Documentation

GET /swap/{id} returns the latest status for a swap created with your API key. Poll every 30 seconds while the status is not terminal.

Statuses

Status	Meaning
`waiting_deposit`	Waiting for the user to send funds.
`deposit_detected`	A deposit was detected and is waiting for confirmations.
`underpaid`	The detected deposit amount was incomplete.
`processing`	The swap is being processed.
`completed`	The swap finished.
`refunded`	Funds were refunded.
`failed`	The swap failed.
`expired`	The deposit was not detected before the deadline.

Terminal statuses: completed, refunded, failed, expired.

Underpaid swaps

underpaid is not terminal. The deposit arrived below the quoted amount and the swap is waiting for the route to settle the outcome. Keep polling: the swap can still move to processing and completed, or end as refunded or failed. Do not ask the user to send more funds unless LightSwap support tells you to.

Error format

All errors use the same response shape:

{
  "error": {
    "code": "quote_expired",
    "message": "Quote has expired.",
    "details": {}
  },
  "requestId": "request-id"
}

Error codes

Code	Meaning	Suggested handling
`invalid_api_key`	The API key is missing or invalid.	Check backend configuration.
`inactive_partner`	API access is disabled.	Contact LightSwap.
`validation_error`	The request body, headers, or parameters are invalid.	Fix the request and retry.
`unsupported_asset`	The requested asset is not available for that network.	Refresh assets and ask the user to choose another asset.
`unsupported_memo`	A memo was supplied for a network that does not support memos, or no route that can carry a memo is available for the pair.	Remove the memo and retry, or use a self-custody destination or another pair.
`unsupported_pair`	The requested pair is not available.	Ask the user to choose another pair or amount.
`quote_not_found`	The quote ID does not exist for your API key.	Create a new quote.
`quote_expired`	The quote expired before swap creation.	Create a new quote.
`quote_already_used`	The quote already created a swap.	Repeating `POST /swap` with the same `quoteId` returns the existing swap. If you still see this error, create a new quote.
`rate_limited`	The request limit was exceeded.	Wait for `Retry-After`, then retry.
`provider_unavailable`	A route service is temporarily unavailable.	Retry later or ask the user to choose another pair.
`swap_not_found`	The swap ID does not exist for your API key.	Check the stored swap ID.
`internal_error`	The request failed on the server.	Retry later. If it continues, contact support with your `externalId` and swap ID.

Troubleshooting

Situation	What to do
Quote expires before the user confirms	Create a new quote and show the updated estimate.
Address validation fails	Ask the user to check the address and selected network.
Swap remains `waiting_deposit`	Confirm the user sent the exact asset to the displayed deposit address before the deadline.
Swap is `underpaid`	Do not ask the user to send more unless LightSwap tells you to.
API returns `rate_limited`	Back off using `Retry-After`; avoid tight retry loops.

For what to tell end users when a swap goes wrong, see Refunds.