# API Rules

## Basic Information

All API requests must use HTTPS. The access endpoints are as follows:

| Endpoint | Environment | Notes |
|  --- | --- | --- |
| https://open-fat.cb.paykka.com | Sandbox |  |
|  | Production | Offline application |


## Data Format

- Use JSON as the data exchange format for message bodies
- Request headers must include


```header
Content-Type: application/json
Accept: application/json
```

Note: Excluding file upload APIs

## Parameter Compatibility

- Request success does not depend on the order of request parameters
- Request success does not depend on the order of key-value pairs in the request JSON
- When processing responses, do not assume any specific order of key-value pairs in the response JSON
- New API versions may add new parameters or JSON key-value pairs to requests or responses
- New API versions will not remove required parameters or JSON key-value pairs already present in requests and responses
- When a JSON key-value pair in a request or response is empty (null), it may be omitted


## Character Encoding

Use UTF-8 as the message body encoding

## Time Format

All time objects use the format defined by ISO 8601.
The timezone portion uses UTC (denoted by the character Z)

Example message:

```json
{
  "date": "2023-12-04T23:25:59Z"
}
```

The `date` field in the above message represents UTC time 2023-12-04 23:25:59, which corresponds to Beijing time (UTC+8) 2023-12-05 07:25:59.

## Error Information

HTTP status codes are used to indicate the result of request processing

| Status Code | Description |
|  --- | --- |
| 200 | The request was processed correctly |
| 4xx | The request was not processed due to errors in the request content: format errors / parameter integrity errors / non-existent request objects / status errors / insufficient balance, etc. |
| 5xx | An exception occurred during processing, and the request was not processed: network failure / program defects, etc. |


## Error Codes and Error Messages

When a request fails, in addition to the HTTP status code indicating the error, the API will return an error response in the message body explaining the specific error cause.

| Key | Type | Description |
|  --- | --- | --- |
| ret_code | String(6) | Error code |
| ret_msg | String | Error response message, describing the specific error |


## Common Error Codes and Descriptions

| Error Code | Description |
|  --- | --- |
| 999999 | Unknown exception (please contact platform technical staff) |
| 010000 | Request parameter error (format error, missing parameters, etc.) |
| 010001 | Request too frequent |
| 010002 | Request data does not exist |
| 010003 | Incorrect request data status |
| 010004 | Data integrity violation |
| 010005 | File size limit exceeded |
| 010100 | Unauthenticated request (commonly due to signature verification failure) |
| 010200 | Unauthenticated request (commonly due to signature verification failure) |