API Responses

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:

boolean

required

Indicates whether the request was successful. Value will be true or false.

string | object

Contains error information if the request failed. Empty string if successful.

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

boolean

required

Always true for successful requests

string

Empty string for successful requests

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

string

required

Always "false" for error responses (note: string, not boolean)

object

required

Contains error details

Show Error object properties

string

Human-readable error description

string

Machine-readable error code for programmatic handling

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);
}

import requests

response = requests.get(
    'https://api.cashqbot.com/api/agent_balance',
    headers={'API-KEY': api_key}
)

data = response.json()

if data.get('success') in [True, 'true']:
    # Handle success
    print('Balance:', data['balance'])
else:
    # Handle error
    print('Error:', data['error']['message'])

$response = file_get_contents(
    'https://api.cashqbot.com/api/agent_balance',
    false,
    stream_context_create([
        'http' => [
            'header' => "API-KEY: $apiKey"
        ]
    ])
);

$data = json_decode($response, true);

if ($data['success'] === true || $data['success'] === 'true') {
    // Handle success
    echo 'Balance: ' . $data['balance']['balance'];
} else {
    // Handle error
    echo '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 Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
500	Internal Server Error	Server 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

Getting started

Core Concepts

Response Format

Response Envelope

Success Response

Example Success Response

Success Response Structure

Error Response

Example Error Response

Error Response Structure

Response Examples by Endpoint

Balance Response

KYC Verification Response

Transfer Status Response

Check Transfer Response

Handling Responses

Checking Success

Error Handling

HTTP Status Codes

Best Practices

Always Check Success

Handle Both Types

Use Error Codes

Log Responses

Next Steps

Error Handling

API Reference

​Response Format

​Response Envelope

​Success Response

​Example Success Response

​Success Response Structure

​Error Response

​Example Error Response

​Error Response Structure

​Response Examples by Endpoint

​Balance Response

​KYC Verification Response

​Transfer Status Response

​Check Transfer Response

​Handling Responses

​Checking Success

​Error Handling

​HTTP Status Codes

​Best Practices

Always Check Success

Handle Both Types

Use Error Codes

Log Responses

​Next Steps

Error Handling

API Reference

Response Format

Response Envelope

Success Response

Example Success Response

Success Response Structure

Error Response

Example Error Response

Error Response Structure

Response Examples by Endpoint

Balance Response

KYC Verification Response

Transfer Status Response

Check Transfer Response

Handling Responses

Checking Success

Error Handling

HTTP Status Codes

Best Practices

Next Steps