Skip to main content

​
Response Format

All CashQ API responses are in JSON format and share a consistent envelope structure.

​
Response Envelope

Every API response includes these top-level attributes:
​
success
boolean
required
Indicates whether the request was successful. Value will be true or false.
​
error
string | object
Contains error information if the request failed. Empty string if successful.
​
data
object
Contains the response data for successful requests. Structure varies by endpoint.

​
Success Response

When a request succeeds, success will be true and the response will include relevant data.

​
Example Success Response

{
  "payment_response": {
    "payment_id": null,
    "state": "-2",
    "substate": "0",
    "code": "0",
    "id": "123456789"
  },
  "error": "",
  "success": true
}

​
Success Response Structure

​
success
boolean
required
Always true for successful requests
​
error
string
Empty string for successful requests
​
[data_field]
object
Response data specific to the endpoint (e.g., payment_response, balance, status)

​
Error Response

When a request fails, success will be false and the response will include error details.

​
Example Error Response

{
  "error": {
    "message": "An error occurred while we were processing your request",
    "code": "internal_server_error"
  },
  "success": "false"
}

​
Error Response Structure

​
success
string
required
Always "false" for error responses (note: string, not boolean)
​
error
object
required
Contains error details

​
Response Examples by Endpoint

​
Balance Response

{
  "balance": {
    "balance": 0,
    "overdraft": 2000
  }
}

​
KYC Verification Response

Verified User: 
{
  "kyc_verify": true,
  "money_limit": "8990",
  "kyc_url": ""
}
Unverified User: 
{
  "kyc_verify": false,
  "money_limit": "600",
  "kyc_url": "https://link.cashqbot.com/j2tf"
}

​
Transfer Status Response

{
  "status": {
    "result": {
      "server_time": null,
      "code": 0,
      "substate": 0,
      "id": "123456789",
      "state": 40,
      "attribute": [],
      "trans": null,
      "sum_prov": null,
      "final": 0
    }
  }
}

​
Check Transfer Response

{
  "error": "",
  "success": true
}

​
Handling Responses

​
Checking Success

Always check the success field first to determine how to process the response: 
const response = await fetch('https://api.cashqbot.com/api/agent_balance', {
  headers: { 'API-KEY': apiKey }
});

const data = await response.json();

if (data.success === true || data.success === 'true') {
  // Handle success
  console.log('Balance:', data.balance);
} else {
  // Handle error
  console.error('Error:', data.error.message);
}
Type InconsistencyNote that success is a boolean (true/false) for successful responses but a string ("false") for error responses. Always check for both types in your code.

​
Error Handling

Use the error code for programmatic error handling: 
if (data.success !== true) {
  switch (data.error.code) {
    case 'authentication_error':
      // Handle authentication issues
      break;
    case 'insufficient_funds':
      // Handle insufficient balance
      break;
    case 'internal_server_error':
      // Handle server errors
      break;
    default:
      // Handle unknown errors
      console.error(data.error.message);
  }
}

​
HTTP Status Codes

The CashQ API uses standard HTTP status codes:
Status CodeMeaningDescription
200OKRequest succeeded
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
404Not FoundResource not found
500Internal Server ErrorServer error occurred
Even when the HTTP status is 200, always check the success field in the response body to determine if the operation succeeded.

​
Best Practices

Always Check Success

Check the success field before processing response data

Handle Both Types

Account for success being both boolean and string

Use Error Codes

Use error codes for programmatic error handling

Log Responses

Log full responses for debugging and monitoring

​
Next Steps

Error Handling

Learn about specific error codes and how to handle them

API Reference

Explore detailed endpoint documentation