Common Errors

Troubleshooting

Common Errors

A field guide to the errors we see most often when integrating against the CoinPayments API — what they mean, why they happen, and how to fix them. Anchor deep-link each section so you can share specific causes with teammates.

Authentication Guide Contact Integrations Team

Authentication & Authorization

3 items

Anything that gets your request rejected before it runs.

Unauthorized401

The request failed authentication — usually a bad signature, expired credentials, or missing headers.

Common Causes

An invalid clientId or clientSecret.
The integration has been deleted or disabled on the dashboard.
The account hasn't completed business verification.
The API signature is constructed incorrectly — order or encoding wrong.
One of the required headers is missing.

Review Authentication and the Generate Signature guide. If the signature checks out, regenerate the client secret to rule out a leaked or rotated key.

Stale Signature · Timestamp Drift

A request whose timestamp is more than 60 seconds away from server time will be rejected even if the signature is otherwise valid.

Common Causes

Server clock drift on the client machine.
Signing once at startup and reusing the signature for many later requests (signatures are per-request, not per-session).
Queueing requests in a background job and signing them at enqueue time instead of dispatch time.

Re-sign each request just before sending it. Use NTP to keep your server clocks in sync, and format the timestamp as YYYY-MM-DDTHH:mm:ss in UTC — no milliseconds, no timezone suffix.

IP Not Allowed

The integration has an IP whitelist configured, and the request originated from an IP that isn't on the list.

Common Causes

Requests proxied through a cloud provider with rotating egress IPs.
Local development traffic when only production IPs are whitelisted.
Moving to a new datacenter or container host without updating the integration.

Update the integration's Allowed IPs on the dashboard, or remove the whitelist entirely if you don't need IP pinning.

Validation

4 items

Your request reached us but didn't pass schema checks.

Bad Request400

The body or query parameters failed validation. The response body contains a precise description of which field is invalid.

Common Causes

Missing a required parameter — check the route's request schema.
Sending the wrong type (e.g. string where a number is expected, or a number where a string-encoded amount is expected).
Numeric amounts exceeding the precision the chain supports.

Look up the route in the API Routes reference and check the response body for the exact validation error message.

Invalid Address

A withdrawal or conversion target address is malformed or doesn't match the format expected for the currency.

Common Causes

Address encoded for a different network (see Network Mismatch below).
Typos or truncation — wallet addresses must be copied verbatim.
Using a deposit address from a different exchange that has additional formatting rules.

Valid examples per chain:

BTC · 1BvBMSEYstWetqTFn5...
BCH · bitcoincash:qr7uq7uv…
LTC · LZx9pzGaH6mKSz...
ETH/ERC-20 · 0x7E5F4552191A69125d...

Invalid or Unsupported Currency

The currencyId in your request doesn't exist or isn't supported on your account.

Common Causes

Hard-coded a currencyId that has since been deprecated.
Confused a coin's ticker symbol (e.g. USDT) with its numeric id.
The account hasn't completed business verification.

Look up the canonical id via Supported Currencies before issuing the request.

Network · Chain Mismatch

Sending to an address that exists on a different network than the currency you specified — for example, USDT on Ethereum (ERC-20) sent to a Tron (TRC-20) address.

Common Causes

Multi-chain assets (USDT, USDC) used without specifying the correct network variant.
Pasting an EVM address as the destination for a UTXO chain (or vice versa).

Confirm the destination address belongs to the same network as the currency you're sending. The currencies endpoint exposes the network for every supported asset.

Funds & Limits

2 items

You reached the API, but the transaction itself is constrained.

Insufficient Funds

The originating wallet doesn't have enough balance to cover the transaction amount plus any applicable network and platform fees.

Common Causes

Withdrawing more than the wallet balance.
Forgetting to budget for the network fee on top of the send amount.
Pending conversions or other in-flight transactions that have already used part of the balance.

Fetch the live wallet balance immediately before submitting, and subtract the response from Fees before computing the max send amount.

Rate Limit Exceeded

The API enforces a default cap of 70 requests per second.

Common Causes

Hot-looping over a large dataset without batching.
Polling for status when you could be using webhooks.

Back off and retry with exponential delay, switch long polls to Webhooks, or contact us to discuss a higher quota.

Buyer-Flow Issues

4 items

Not API errors — but the next thing developers ask about.

Underpayment

The buyer sent less than the invoice total — usually because the on-chain network fee was not added on top of the displayed crypto amount.

Common Causes

The client only sent the invoice total and did not account for network fees.
Manual entry or typos when the buyer entered the amount into a wallet.
A third-party sending wallet that auto-subtracts the network fee from the amount before sending.

See Payment Errors → Underpayments for the merchant tolerance settings, the "Accept Partial Payment" flow, and the buyer's resolution options.

Overpayment

The buyer sent more than the invoice total. The invoice still completes; the excess is automatically refunded to the buyer via the standard refund flow.

Common Causes

Buyer entered the wrong amount.
A wallet that pads the amount for fee safety, sending more than the requested total.

You don't need to do anything — see Payment Errors → Overpayments for the buyer-side refund flow and the network-fee floor that suppresses dust refunds.

Invoice Timed Out

The 60-minute exchange-rate lock expired before the payment confirmed. Funds that arrive (or finalise on-chain) after the timer are auto-refunded.

Common Causes

The buyer sat on the checkout page and sent funds too late.
Funds were broadcast inside the window but confirmed past the 60-minute mark.
A slow chain or high mempool congestion delaying confirmations.

Read Payment Timeout for the lifecycle, then Claiming a Refund for the buyer's claim steps.

Auto-Refund Not Issued

CoinPayments will not issue an automatic refund if the excess amount is smaller than the chain's network fee — the dust would be consumed entirely by the broadcast cost.

Common Causes

A very small overpayment on a high-fee chain (e.g. a few cents over on an Ethereum payment).
A high-priority gas spike at the moment the refund was attempted.

This is by design — see the refund triggers for the full list of conditions. There's nothing to recover on the buyer's side when the excess is sub-fee.

Common Misconceptions

1 item

Not strictly errors — but they trip people up the most.

Dashboard Wallet vs API Wallets

The wallet you see in the CoinPayments dashboard UI is segregated from API-created wallets. They share an account but their balances are independent — you cannot move funds between them with a regular API call.

Common Causes

Trying to withdraw from your dashboard balance by referencing it from an integration.
Assuming "the account" exposes a single wallet to the API.
Using a deposit address from the dashboard UI as the source of an API-driven send.

Read UI vs API Wallets to understand the segregation, then create an API wallet via the integration to hold funds that your application can move programmatically.

Still stuck?

Walk through the docs, or talk to a human.

Authentication Guide

Headers, signatures, and how to fix 401s.

Payment Errors

Underpayments, overpayments, timeouts, and refunds.

Contact Integrations Team

Talk to a developer-support engineer.