# 3. Authorization

# Authentication and Authorization

This section explains the **authentication methods**, **authorization scope**, and **security best practices** for the FoxData API, helping callers integrate with the API correctly and securely.

---

## 1. Authentication Methods

The FoxData API currently uses **API Key (request header) authentication**.

- **Header Name**: `x-openapi-key`
- **Header Value**: `<YOUR_LICENSE>` (obtained from the Personal Center or by contacting Sales)

All endpoints requiring authentication must include this request header; otherwise, access will be denied.

---

## 2. Obtaining and Managing API Keys

### How to Obtain

- Copy or modify the API Key in the FoxData Personal Center, or contact our sales team to have one assigned after activation

---

## 3. Explanation of Empty Data

When no data is available based on the query criteria, the following typically occurs:

- `code` remains a success status (e.g., `200`)
- `data.result` returns an empty array `[]` or an empty object `{}` (subject to the API definition)
- This is not considered an API exception

---

## 4. Pagination Interface Description

Some interfaces return `data.next`, which is used to fetch the next page of data:

```json
“next”: {
  “taskId”: “...”,
  “pageKey”: “2”
}
```

- When `next` is `null`, it indicates there is no next page of data, and the query ends.
- The next page can be retrieved using (as shown in the documentation):

- `GET /common/next-page?taskId={taskId}&pageKey={pageKey}`

---

## 5. General Error Codes

This section describes the **business error codes** for the FoxData API (which differ from HTTP status codes). When a request fails, please prioritize troubleshooting based on the `code` and `msg` fields.

### Error Code Table

| Code | Code Description | Notes (Common Causes/Tips) |
|---:|---|---|
| 200 | Request Successful | - |
| 100 | Parameter Error | Invalid parameter format / Missing required parameters / Type mismatch |
| 401 | Missing API Key | `x-openapi-key` request header omitted |
| 403 | Invalid API Key | API Key is invalid/disabled/has been rotated |
| 429 | API Throttled | API access exceeded QPS threshold |
| 510 | System Error | Common in data synchronization error scenarios |
| 60003 | Daily Call Limit Reached | Reached daily quota limit |
| 60004 | Per-Minute Call Limit Reached | Reached per-minute quota/QPS limit |
| 60005 | Insufficient credit balance | Current remaining credit is insufficient to complete this call |
| 60006 | Credit deduction error | Deduction failed/accounting error (please retry later or contact support) |
| 60008 | No data available | Task data has not been fully processed or no data is currently available to return |

### Example Failure Responses (Structure)

Example: Missing API Key (401)

```json
{
  “code”: 401,
  “msg”: “Missing API Key”,
  “data”: null
}
```

Example: Insufficient Credit Balance (60005)

```json
{
  “code”: 60005,
  “msg”: “Insufficient points balance”,
  “data”: null
}
```

Example: No data available (60008)

```json
{
  “code”: 60008,
  “msg”: “No data available”,
  “data”: null
}
```

> Note: In case of failure, `data` may be `null`, `{}`, or `[]`; refer to the specific API response for details. Troubleshooting should prioritize `code` and `msg`.

---