> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.taxwire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Retries, refunds, rate limits and currency exchange

## Retries and network failures

**Does Taxwire send webhooks?** No. The API is synchronous: the response to `POST /transactions` is the saved transaction, with its Taxwire `id`, status and tax.

**Can I retry a quote?** Yes. `POST /calculations` saves nothing, so retry it as often as you need.

**How do I retry recording a sale or refund?** Always send a `reference_id`, derived from your own order or refund number. It must be unique in your account, and it is what stops a retry from recording the same sale twice. If `POST /transactions` fails or times out:

1. **Retry with the same body and the same `reference_id`.**
2. **A `400` saying the `reference_id` already exists means a transaction with it was saved**, most likely by your earlier attempt. Don't retry under a new `reference_id`. Read the saved transaction with [`GET /transactions/by_reference_id/{reference_id}`](https://apidocs.taxwire.com/api-reference/transactions/by-reference-id).
3. **A `404` from that lookup means nothing was saved**, so retry the request.

> [!WARNING]
>
> Don't use `/` in a `reference_id`. The lookup can't find a `reference_id` that contains one, even URL-encoded as `%2F`, and returns `404` for a transaction that exists.

```json theme={null}
{
  "errors": [
    {
      "status": "400",
      "code": "validation_error",
      "title": "Bad Request",
      "detail": "Transaction with reference_id ORD-1001 already exists."
    }
  ]
}
```

Without a `reference_id`, a retry after a timeout can record the sale twice. A `reference_id` stays taken even after its transaction is voided.

**Can I retry an update?** A status change, yes: sending `{"status": "void"}` to a transaction that is already void succeeds. An update that also changes `line_items`, `currency`, `transaction_date` or discounts is only accepted while the transaction is a `draft`, so if the first attempt finalized it, the retry is refused with `400`. Read the transaction with `GET /transactions/{id}` to see where it stands.

**Which errors should I retry?** `429`, `500`, `502`, `503` and `504`, with exponential backoff. On a `429`, wait the number of seconds in the `Retry-After` header first. Don't retry other `4xx` errors unchanged: fix the request. See [Errors](https://apidocs.taxwire.com/api-reference/errors.md).

## Refunds

**Why is my refund refused with `credit_remainder_unknown`?** Taxwire works out how much tax is left to refund on a sale from the tax recorded on the sale and on earlier credits against it. If the sale or an earlier credit has no tax recorded, the credit is refused with `422`:

```json theme={null}
{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Unprocessable Entity",
      "detail": "Validation failed: credit_remainder_unknown"
    }
  ]
}
```

The usual cause is that the sale, or an earlier credit, is still a `draft`. A draft has no tax recorded, even if it was sent with a `tax_amount`. Finalize it with `POST /transactions/{id}` and `{"status": "finalized"}`, then send the credit again. If everything is already finalized, [contact us](mailto:support@taxwire.com) with the sale's `id`.

## Rate limits

**What is the limit?** 10 requests per second per API key, by default.

**Is it per endpoint?** No. Every request made with a key counts against that key's one limit: quotes, transactions, refunds, lookups, customers and products alike. The limit is counted over a moving one-second window.

**How do I know how close I am?** Successful responses carry two headers:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The key's limit, in requests per second. |
| `X-RateLimit-Remaining` | Requests left in the current window. |

**What happens over the limit?** The request is refused with `429` and a `Retry-After` header giving the seconds to wait. Nothing is processed, so the request is safe to retry after that.

**Can the limit be raised?** Yes. Limits are set per account. If you expect more traffic, such as a sale or a launch, [contact us](mailto:support@taxwire.com) with your expected peak and we'll raise it.

## Currency and exchange rates

**Which currency is tax returned in?** The transaction's `currency`. A KRW order gets its tax in KRW, in the currency's smallest unit. See [currency support](https://apidocs.taxwire.com/api-reference/guides/calculate_taxes.md#currency) for the currencies we accept.

**Is an exchange rate used to calculate tax?** Not for percentage taxes, which are most sales taxes and VAT: the rate is applied to your prices in your currency. Only a tax set as a fixed amount per unit (`rate_type: flat_amount` in the response) uses one. That amount is set in the jurisdiction's currency, and Taxwire converts it to the transaction's currency at the exchange rate for the `transaction_date`. Rates come from [Open Exchange Rates](https://openexchangerates.org) and are updated daily.

**Can the tax change between quoting and recording because of exchange rates?** Not for percentage taxes. The tax changes when the inputs change: the items, prices, discounts, addresses or `transaction_date`. It can also change if your account's setup changes in between, for example a new registration or a customer's exemption.

**Can a refund be in a different currency from its sale?** No. A credit with line items in another currency is refused with `422`, and a full refund always takes the sale's currency.

**How are nexus thresholds tracked across currencies?** Taxwire converts your sales into each threshold's currency, USD for US states, at each day's exchange rate. You don't need to send converted amounts.

**Why does tax include a fraction of the smallest unit?** Tax is calculated precisely, so a line's tax can be, for example, `"82.5"` cents. Round the order's `tax_amount` once, when you charge the buyer, rather than rounding each line.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.