Statuses and errors

Use GET /swap/{id} to show the latest status for a swap created with your API key. If you set externalId on quote creation, keep it with the swap record and use it as your first support reference. Add the LightSwap swap ID when one already exists.

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

Poll every 30 seconds while the status is not terminal.

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_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.	Retry `POST /swap` with the same `quoteId` or use the stored swap ID.
`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 and contact support with your `externalId` and swap ID if it continues.

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.

Overview

Integrations

API Reference

Support

Statuses

Error format

Error codes

Troubleshooting

​Statuses

​Error format

​Error codes

​Troubleshooting

Statuses

Error format

Error codes

Troubleshooting