```php
## Timestamped HMAC Signature
`POST /v1/withdrawals` requires a Unix timestamp within 300 seconds of server time. Other authenticated endpoints also accept this mode when `Timestamp` or `X-Timestamp` is supplied.
```text
canonical_body = canonical_json(request_object) or "" for a bodyless request
payload_base64 = base64_utf8(canonical_body)
message = payload_base64 + "." + Timestamp
Sign = hmac_sha256(message, API_KEY)
```
Send exactly the timestamp string used in the signature:
```text
Merchant: 12345678-1234-1234-1234-123456789012
Timestamp: 1716200000
Sign: 64-character-lowercase-hmac-sha256-hex
```
```php
The timestamp prevents stale replay but does not make a write idempotent. In particular, it is unsafe to automatically repeat a withdrawal after an unknown outcome.
## Complete Invoice Example
```javascript
const crypto = require('node:crypto')
function canonicalJson(payload) {
return JSON.stringify(payload)
.replace(/\//g, '\\/')
.replace(/[\u0080-\uFFFF]/g, character =>
`\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`
)
}
const payload = {
order_id: 'order_12345',
amount: '100.50',
success_url: 'https://merchant.example/success'
}
const body = canonicalJson(payload)
const payloadBase64 = Buffer.from(body, 'utf8').toString('base64')
const sign = crypto.createHash('md5').update(payloadBase64 + process.env.COINSSEND_API_KEY).digest('hex')
const response = await fetch('https://api.coinssend.com/v1/invoices', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Merchant: process.env.COINSSEND_MERCHANT_ID,
Sign: sign
},
body
})
```
## GET Requests
For an authenticated GET with no body, the canonical body and Base64 payload are both empty. The legacy signature is therefore:
```text
Sign = md5("" + API_KEY)
```
Do not add merchant signature headers to public `GET /v1/invoices/{invoiceCode}`, `GET /v1/get-coin-rate`, or `GET /v1/coins-and-fee` calls.
## Authentication Errors
Authentication failures return a compact body such as:
```json
{
"error": "Invalid sign"
}
```
| HTTP status | Message | Meaning |
| ----------- | ------------------------------- | ----------------------------------------------------- |
| `400` | `Missing headers` | `Merchant` or `Sign` is missing |
| `400` | `Missing timestamp` | Withdrawal timestamp is missing |
| `401` | `Invalid merchant` | Merchant or API key was not found |
| `401` | `Invalid sign` | Signature verification failed |
| `401` | `Timestamp expired` | Timestamp is invalid or outside the 300-second window |
| `403` | `Merchant account is suspended` | Merchant is suspended |
These messages are not a separate `code` property. Endpoint and validation
errors use different documented shapes; always branch on the HTTP status and
then parse the applicable schema.
## Operational Guidance
- Keep the API key in a secrets manager or server environment variable.
- Generate and send the body as one immutable string.
- Use a clock synchronized with NTP for withdrawal timestamps.
- Compare webhook HMAC values in constant time; webhook signing is a separate raw-body contract described in [Webhooks](https://docs.coinssend.com/webhooks.md).
- Use the published test vectors in automated client tests before making live calls.
---
Source: https://docs.coinssend.com/error-handling.md
# Error Handling
CoinsSend does not use one universal error envelope and does not guarantee a
symbolic `code` field. Branch on HTTP status first, then parse the applicable
documented shape.
## Success Envelope
Most successful operations return:
```json
{
"data": {},
"status": "success"
}
```
Successful write operations currently return HTTP `200`, including asynchronous
withdrawal submission.
## Error Shapes
### Authentication Errors
Header authentication failures return only `error`:
```json
{
"error": "Invalid sign"
}
```
Verified messages include `Missing headers`, `Missing timestamp`,
`Invalid merchant`, `Invalid sign`, `Timestamp expired`, and
`Merchant account is suspended`.
### Endpoint Errors
Endpoint failures normally return:
```json
{
"status": "error",
"message": "Order id already exists"
}
```
Some endpoints add fields at the top level. Provider-card failures add
`failure_code`; withdrawal failures can add amounts and fee details. Treat
human-readable message text as descriptive rather than a stable machine code.
### Validation
Validation failures use HTTP `422`:
```json
{
"errors": {
"amount": [
"The amount field is required."
]
},
"status": "error",
"message": "The given data was invalid."
}
```
### Rate Limiting
The wallet-creation limit returns `status` and `message`. Other HTTP `429`
responses may use a different shape or include `retry_after` and a
`Retry-After` header. Treat rate-limit metadata as optional; see
[Rate Limits and Safe Retries](https://docs.coinssend.com/rate-limits.md).
## HTTP Statuses
| Status | Meaning in the public contract |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `400` | Missing auth input or an endpoint rejection. Withdrawal permission denial currently uses this status. |
| `401` | Invalid merchant/signature or expired timestamp. |
| `403` | Suspended/blocked merchant state or authorization failure. |
| `404` | Public invoice or QR resource not found. |
| `409` | Invoice `order_id` already exists, or wallet creation is already in progress. |
| `422` | Request validation or provider-card capability/state failure. |
| `429` | A rate limit was exceeded. |
| `500` | Unexpected application failure. |
| `502` | Provider-card checkout could not obtain a usable provider response. |
## Endpoint-Specific Cases
The labels in this table are suggested **client-side categories**. They are not
wire fields returned by CoinsSend.
| Client category | HTTP status | Endpoint / condition | Wire shape |
| ------------------------------ | ------------- | ----------------------------------------------------- | ----------------------------------------- |
| `missing_headers` | `400` | Authenticated endpoint without Merchant or Sign | `{"error":"Missing headers"}` |
| `missing_timestamp` | `400` | Withdrawal without Timestamp/X-Timestamp | `{"error":"Missing timestamp"}` |
| `invalid_signature` | `401` | Signature mismatch | `{"error":"Invalid sign"}` |
| `timestamp_expired` | `401` | Invalid or stale timestamp | `{"error":"Timestamp expired"}` |
| `invoice_order_conflict` | `409` | Duplicate merchant `order_id` | endpoint error |
| `validation_failed` | `422` | Invalid invoice, wallet, or withdrawal input | validation error |
| `withdrawal_permission_denied` | `400` | API key lacks withdrawal permission | endpoint error |
| `withdrawal_rejected` | `400` | Balance/fee/service rejection | endpoint error with possible extra fields |
| `provider_card_unavailable` | usually `422` | Current availability or invoice state blocks checkout | endpoint error with `failure_code` |
| `wallet_creation_in_progress` | `409` | Merchant-scoped wallet lock conflict | endpoint error |
## Robust Parsing
```php
## Retry Safety
Automatically retry only verified read operations with bounded exponential
backoff and jitter. A timeout on a write does not prove the server rejected it.
- Duplicate invoice `order_id` returns `409`; it does not replay the first
response.
- Withdrawals have no request idempotency key.
- Static-wallet creation can create another address when repeated.
- Provider-card creation only reuses an already-active order; this is not a
general idempotency contract.
Reconcile an unknown write outcome instead of blindly resubmitting it. Full
guidance is in [Rate Limits and Safe Retries](https://docs.coinssend.com/rate-limits.md).
## Troubleshooting Invalid Signatures
- Generate the PHP-compatible canonical JSON described in
[Authentication](https://docs.coinssend.com/authentication.md).
- Sign and send the same immutable canonical string.
- Use strings for monetary amounts.
- For withdrawals, recompute a fresh timestamp and HMAC.
- Run the client against
[`signature-test-vectors.json`](https://docs.coinssend.com/signature-test-vectors.json), including the
URL/Unicode vector.
- Remember that webhook verification is different: it uses the exact raw
received body bytes.
The exact machine-readable response schemas are in
[OpenAPI](https://docs.coinssend.com/openapi.json).
---
Source: https://docs.coinssend.com/rate-limits.md
# Rate Limits and Safe Retries
The public contract does not promise universal `X-RateLimit-*` headers or one
fixed global request count. Clients must handle HTTP `429` on any operation.
## Documented Wallet-Creation Limit
`POST /v1/wallet-address` has this merchant limit:
- threshold: 100 successful wallet creations;
- window: 60 seconds;
- key: current merchant;
- failed creation attempts are not counted;
- rejection: HTTP `429` with `status` and `message`.
Example:
```json
{
"status": "error",
"message": "Too many requests. Please try again later."
}
```
This response does not currently guarantee
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`,
`Retry-After`, or `retry_after`.
## Additional Limits
Additional limits may apply. Their response bodies and headers are not part of
a universal contract. Clients should tolerate HTTP `429` whether or not
`Retry-After` is present.
## Retry Decision Table
| Operation | Automatic retry after `429` or transport failure? | Reason |
| ------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /v1/get-coin-rate` | Yes, with bounded backoff | Read-only public discovery |
| `GET /v1/coins-and-fee` | Yes, with bounded backoff and caching | Read-only public discovery |
| `GET /v1/merchants/balances` | Yes, with a fresh signature/timestamp when used | Read-only merchant state |
| `GET /v1/merchants/fees` | Yes, with a fresh signature/timestamp when used | Read-only merchant state |
| `GET /v1/invoices/{invoiceCode}` | Yes | Read-only checkout state |
| `GET /v1/wallet-addresses/{walletAddress}/qr` | Yes | Read-only binary response |
| `POST /v1/invoices` | No blind retry after an unknown outcome | `order_id` uniqueness returns `409`; it does not replay the original response |
| `POST /v1/withdrawals` | No | No request idempotency key; timestamp freshness is not idempotency |
| `POST /v1/wallet-address` | No for static wallets | A successful retry can create another address |
| `POST /v1/invoices/{invoiceCode}/provider-card-orders` | Do not generalize | Only an already-active order is reused; there is no general `Idempotency-Key` contract |
An HTTP response proves whether a request was rejected. A client-side timeout
does not: the server may already have accepted the write.
## Backoff for Safe Reads
For read operations, use bounded exponential backoff with jitter:
```javascript
async function retrySafeRead(makeRequest, maxAttempts = 4) {
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
const response = await makeRequest()
if (response.status !== 429 || attempt === maxAttempts) {
return response
}
const retryAfterHeader = response.headers.get('Retry-After')
const retryAfter = retryAfterHeader === null ? Number.NaN : Number(retryAfterHeader)
const baseDelayMs = Number.isFinite(retryAfter)
? retryAfter * 1000
: Math.min(500 * 2 ** (attempt - 1), 8000)
const jitterMs = Math.floor(Math.random() * 250)
await new Promise(resolve => setTimeout(resolve, baseDelayMs + jitterMs))
}
}
```
For timestamp-signed reads, recompute `Timestamp` and `Sign` for each attempt.
Never sleep and reuse a timestamp that can age beyond the 300-second signature
window.
## Handling an Unknown Write Outcome
1. Persist the client order/reference and request intent before sending.
2. If a complete success response arrives, persist the returned CoinsSend ID.
3. If the result is unknown, do not issue a blind duplicate.
4. Reconcile using a known returned/public identifier where one exists, or
investigate through merchant operations/support.
5. For withdrawals, wait for the signed withdrawal webhook when an ID was
obtained; otherwise escalate the unknown outcome instead of resubmitting.
## Monitoring
- Record endpoint, HTTP status, request correlation data, and `Retry-After` when
present; never log the API key or full `Sign` header.
- Separate application `429` responses from edge `429` responses.
- Alert on sustained rate limiting and unknown outcomes for write operations.
- Cache the catalog according to its advertised 900-second cache lifetime.
For request-signature freshness and canonicalization, see
[Authentication](https://docs.coinssend.com/authentication.md). For exact operation metadata, see
[OpenAPI](https://docs.coinssend.com/openapi.json).