Errors and troubleshooting

Separate signing failures from account prerequisites and invalid request data.

Error responses use an errors array:

{
  "errors": [
    {
      "message": "a short, human-readable summary of the problem"
    }
  ]
}

Read every message in the array, together with the HTTP status and the endpoint’s response documentation.

Authentication errors#

For a 401 response, check these in order:

Headers: include X-API-KEY, X-API-Algorithm, X-API-Timestamp, and X-API-Signature.
Key: confirm the public key is registered, active, and attached to the correct account and environment. Send its exact registered text, including hexadecimal letter case, and use its matching private key.
Time: use current Unix milliseconds, keep your clock synchronized, and sign immediately before sending. The accepted window is one minute either side of server time.
URL and method: sign the exact method and absolute URL, including query ordering and encoding. Do not follow a redirect with the original signature.
Body: hash the bytes sent. Use an empty string for a bodyless GET. Resolve variables before hashing JSON.
Signature format: use secp256k1, SHA-256, ASN.1 DER, and uppercase hexadecimal. Hash the signing string once; avoid double hashing with libraries that hash internally.
Access: confirm the key has the scope needed by the endpoint and that your service’s outbound IP matches any allowlist configured for the key.

See authentication for the full signing recipe. Share the HTTP method, endpoint, status, error message, and request time when asking Coinhako for help. Never share the private key.

Account and request errors#

Error or symptom	What to check
2FA required	Enable authenticator-app 2FA (TOTP) in the Coinhako app. The quote and order endpoints check that specific account setting.
Account not permitted to transact (`403`)	Confirm account eligibility and onboarding with Coinhako. A valid signature does not override account restrictions.
Risk assessment incomplete	Complete the account’s required assessment and onboarding before trading.
Insufficient balance	Check the available balance in the payment currency. Withdrawals need enough for the amount plus the fee.
Maximum order amount exceeded	Check account limits and pair availability with Coinhako. A limit of zero can indicate an account or pair configuration issue.
Invalid or expired quote	Use the latest matching quote from this account before `expires_at`. A quote already used for an order or superseded by a newer matching quote is unusable.
Duplicate `client_order_id`	Find the original order in the order list. The ID must be unique per account; repeating creation does not return the original success response.
Empty address list	Check account, environment, filters, and pagination. Add the destination and complete any required verification if it is not saved.
Address not found (`404`)	Use the address-book ID belonging to that account, not the blockchain address or an ID from another environment.
Network disabled	Check the selected asset and network’s availability for your account. A supported network may still be unavailable for a particular operation.
Transfer limit or cooling period	Check account and saved-address limits. Contact Coinhako if the restriction needs clarification.
Recipient or VASP information missing	Complete the saved address’s recipient and wallet details. These are not supplied as nested fields on the withdrawal request.

Retry carefully#

A 422 response usually needs a change to request data or account setup. Repeating the same request will not fix it.

For a documented 503 response, follow its Retry-After header when provided. Generate a fresh timestamp and signature for each retry.

If an order or withdrawal request times out, check the order or withdrawal list before resubmitting. The operation may have succeeded even though you did not receive the response.

For orders, match your saved client_order_id and retain it for any retry of the same intended order. Its per-account uniqueness prevents another order with the same ID, but the API does not automatically replay the earlier response. For crypto withdrawals, request_id currently provides no duplicate prevention. See trading and withdrawal tracking .