Skip to main content
Coinut APIs return JSON envelopes for both success and errors.

​
Success envelope

{
  "status": "SUCCESS",
  "data": {}
}

​
Error envelope

{
  "status": "INVALID_PARAMETERS",
  "message": "invalid parameters"
}

​
HTTP status model

HTTP statusMeaning
200Request succeeded
401Authentication failed
422Request was authenticated but invalid or could not be processed
429Rate limit exceeded
500Temporary server error

​
Common error statuses

StatusMeaningRecommended action
INVALID_PARAMETERSMissing or invalid parameterCompare request against the API Reference schema
UNAUTHORISEDSignature, key, timestamp, or nonce is invalidRebuild the canonical string and verify server clock
FAILEDInternal or downstream processing failureRetry only when the operation is safe to retry

​
Retry guidance

Retry transient 429 and 500 responses with exponential backoff. Do not automatically retry money-moving POST requests unless your integration has an idempotency strategy and has checked the current object state. 
async function retryTransient<T>(fn: () => Promise<Response>, maxRetries = 4): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fn();
    if (![429, 500].includes(response.status)) return response;

    const delayMs = 1000 * Math.pow(2, attempt);
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("Coinut API retry limit exceeded");
}

​
Idempotency

  • Generate a fresh nonce for each new API request.
  • For network failures, query detail/list endpoints before retrying create actions.
  • Store your own stable references such as externalId and payment reference.
  • Make webhook processing idempotent because retries are expected.