> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycashq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Responses

> Understanding CashQ API response structure and formats

## 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:

<ParamField path="success" type="boolean" required>
  Indicates whether the request was successful. Value will be `true` or `false`.
</ParamField>

<ParamField path="error" type="string | object">
  Contains error information if the request failed. Empty string if successful.
</ParamField>

<ParamField path="data" type="object">
  Contains the response data for successful requests. Structure varies by endpoint.
</ParamField>

## Success Response

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

### Example Success Response

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

### Success Response Structure

<ResponseField name="success" type="boolean" required>
  Always `true` for successful requests
</ResponseField>

<ResponseField name="error" type="string">
  Empty string for successful requests
</ResponseField>

<ResponseField name="[data_field]" type="object">
  Response data specific to the endpoint (e.g., `payment_response`, `balance`, `status`)
</ResponseField>

## Error Response

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

### Example Error Response

```json theme={null}
{
  "error": {
    "message": "An error occurred while we were processing your request",
    "code": "internal_server_error"
  },
  "success": "false"
}
```

### Error Response Structure

<ResponseField name="success" type="string" required>
  Always `"false"` for error responses (note: string, not boolean)
</ResponseField>

<ResponseField name="error" type="object" required>
  Contains error details

  <Expandable title="Error object properties">
    <ResponseField name="message" type="string">
      Human-readable error description
    </ResponseField>

    <ResponseField name="code" type="string">
      Machine-readable error code for programmatic handling
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Examples by Endpoint

### Balance Response

```json theme={null}
{
  "balance": {
    "balance": 0,
    "overdraft": 2000
  }
}
```

### KYC Verification Response

**Verified User:**

```json theme={null}
{
  "kyc_verify": true,
  "money_limit": "8990",
  "kyc_url": ""
}
```

**Unverified User:**

```json theme={null}
{
  "kyc_verify": false,
  "money_limit": "600",
  "kyc_url": "https://link.cashqbot.com/j2tf"
}
```

### Transfer Status Response

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

### Check Transfer Response

```json theme={null}
{
  "error": "",
  "success": true
}
```

## Handling Responses

### Checking Success

Always check the `success` field first to determine how to process the response:

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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'])
  ```

  ```php PHP theme={null}
  $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'];
  }
  ```
</CodeGroup>

<Warning>
  **Type Inconsistency**

  Note 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.
</Warning>

### Error Handling

Use the error code for programmatic error handling:

```javascript theme={null}
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      |

<Info>
  Even when the HTTP status is 200, always check the `success` field in the response body to determine if the operation succeeded.
</Info>

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Check Success" icon="check">
    Check the `success` field before processing response data
  </Card>

  <Card title="Handle Both Types" icon="code">
    Account for `success` being both boolean and string
  </Card>

  <Card title="Use Error Codes" icon="list">
    Use error codes for programmatic error handling
  </Card>

  <Card title="Log Responses" icon="file-lines">
    Log full responses for debugging and monitoring
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/concepts/errors">
    Learn about specific error codes and how to handle them
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/balance">
    Explore detailed endpoint documentation
  </Card>
</CardGroup>