Errors & Troubleshooting

Errors & Troubleshooting

This page describes the standard error format, common HTTP status codes, and practical troubleshooting steps for the keshflippay Partner API.

---

Standard Error Response

All non-2xx responses return a JSON body:

{
  "status": "error",
  "message": "Human readable description",
  "error": {
    "code": "STRING_CODE",
    "details": {
      "field": "additional context if applicable"
    }
  },
  "correlationId": "req_01HZY5M1N3K4X"
}

• status: Always "error" for failing requests.
• message: Human-readable description for logs or UI.
• error.code: Machine-readable code (see below).
• error.details: Optional object with structured context.
• correlationId: Attach this when contacting support.

---

HTTP Status Codes

Code	Meaning	Typical Causes
400	Bad Request	Validation failed, malformed JSON, missing fields
401	Unauthorized	Signature invalid/missing headers, expired timestamp
403	Forbidden	Missing scope, inactive partner, KYC/limits
404	Not Found	Resource ID incorrect or not visible to partner
409	Conflict	Idempotency collision, duplicate action
422	Unprocessable Entity	Business rule violation (e.g., amount too small)
429	Too Many Requests	Rate limit exceeded
5xx	Server Error	Transient system or dependency failure

---

Common Scenarios

1) Validation Errors (400 / 422)

Example

{
"status": "error",
"message": "Validation failed",
"error": {
  "code": "VALIDATION_ERROR",
  "details": {
    "amount": "Must be a positive decimal string"
  }
},
"correlationId": "req_01HZY..."
}

Fix: Validate field types and required fields before calling the API.

---

2) Authentication Errors (401)

Caused by missing/invalid signature or timestamp drift.

Checklist

• Provide headers X-API-Key, X-Timestamp, X-Signature.
• Build the message: METHOD|PATH|TIMESTAMP|BODY (exact JSON string; empty for GET).
• Ensure timestamp is current UNIX seconds; keep servers time-synced.
• Hex-encode the HMAC-SHA256 signature.

See Authentication & Security.

---

3) Authorization Errors (403)

Partner lacks scope or is restricted.

Fix: Verify required scopes for the endpoint (e.g., withdrawal:create, address:read) or contact support if your account should have access.

---

4) Not Found (404)

Wrong resource ID or resource does not belong to your partner.

Fix: Double-check IDs and ensure you’re using the correct environment (sandbox vs production).

---

5) Idempotency Conflicts (409)

A prior request with the same idempotencyKey is already processed with a different payload.

Example

{
"status": "error",
"message": "Idempotency key already used with different payload",
"error": {
  "code": "IDEMPOTENCY_CONFLICT"
},
"correlationId": "req_01HZ..."
}

Fix: Use a unique idempotency key per intended unique action. Reuse only when retrying the exact same payload.

---

6) Rate Limits (429)

Headers are included to help you backoff:

Header	Description
X-RateLimit-Limit	Max requests in window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	UNIX seconds until reset
X-RateLimit-Window	Window size in seconds

Fix: Implement exponential backoff and honor X-RateLimit-Reset.

---

7) Server Errors (5xx)

Transient failures or dependency timeouts.

Fix: Retry with exponential backoff and idempotency keys for POST-like operations.

---

Troubleshooting Checklist

1. Path & Method: Ensure PATH exactly matches /api/v1/... used in signing.
2. Body Canonicalization: Use the exact JSON string in the signature; avoid spaces or field order changes between signing and sending.
3. Timestamp: Use Math.floor(Date.now()/1000) (Node) or int(time.time()) (Python).
4. Headers: Set Content-Type: application/json and required auth headers.
5. Network: Confirm TLS (HTTPS) and firewall allow outbound traffic.
6. Retry Policy: Backoff on 429 / 5xx. Use idempotencyKey for create flows.
7. Compare Environments: Sandbox vs Production base URL.
8. Capture Correlation ID: Log and share correlationId with support.

---

Example: Error Handling (cURL)

Terminal

curl -i -X POST "https://api.keshflippay.com/api/v1/crypto/withdrawals" -H "Content-Type: application/json" -H "X-API-Key: <apiKey>" -H "X-Timestamp: <ts>" -H "X-Signature: <sig>" -d '{"chainId":"1","asset":"USDC","amount":"-1","toAddress":"0x..."}'

---

Client-Side Patterns

JavaScript

handleError.js

try {
const res = await client.request("POST", "/crypto/withdrawals", {/*...*/});
console.log(res);
} catch (err) {
console.error("Status:", err.status);
console.error("Message:", err.message);
console.error("Payload:", err.response?.data);
}

Python

handle_error.py

try:
  res = client.request("POST", "/crypto/withdrawals", {"chainId":"1", "asset":"USDC", "amount":"-1"})
  print(res)
except Exception as e:
  print("Error:", str(e))

---

Contact & Support

If issues persist, capture the correlationId and contact support with the request time, environment, and the failing endpoint.