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

# Requests responses

API request format, response structure, and error handling.

## Quick Start

1. Use JSON for request and response bodies with `Content-Type: application/json`.
2. Authenticate as required by the API (e.g. sign, or JWT for Issuing endpoints).
3. Handle responses using the numeric `code` and `msg` fields.

## Request Format

### Content Type

* **Content-Type:** `application/json`
* Request bodies must be valid JSON. Responses are JSON.

### Headers

| Header          | Required      | Description                                                      |
| --------------- | ------------- | ---------------------------------------------------------------- |
| `Content-Type`  | Yes           | `application/json`                                               |
| `Authorization` | When required | Bearer token (e.g. JWT for Issuing) or as specified per endpoint |

Some Issuing endpoints may support an `Idempotency-Key` header for POST requests. See the endpoint documentation.

### Example Request

```bash theme={null}
curl -X POST https://<BASE_URL>/v1/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{"name": "My Account", "currency": "USD"}'
```

## Response Format

### Response Body

All responses use the same structure:

* **code** – Numeric result or error code (e.g. 200 for success).
* **msg** – Human-readable message (may be localized).
* **data** – Response payload on success; often `null` on error.

**Success example:**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
```

**Error example:**

```json theme={null}
{
  "code": 559,
  "msg": "sign error!",
  "data": null
}
```

Use the numeric **code** for programmatic handling. The full list of codes is in [Response Codes](../reference/response-codes.md).

### Response Headers

| Header         | Description                                         |
| -------------- | --------------------------------------------------- |
| `x-request-id` | Request identifier; include when contacting support |
| `Content-Type` | `application/json`                                  |
| `Retry-After`  | Present on 429; wait time in seconds                |

### HTTP Status Codes

| Code        | Meaning      | Action                           |
| ----------- | ------------ | -------------------------------- |
| 200         | Success      | Process response data            |
| 201         | Created      | Process response data            |
| 400         | Bad request  | Fix request and retry            |
| 401         | Unauthorized | Check credentials/signature      |
| 403         | Forbidden    | Check permissions                |
| 404         | Not found    | Verify resource ID               |
| 409         | Conflict     | Resolve conflict before retry    |
| 429         | Rate limited | Wait and retry (see Retry-After) |
| 500         | Server error | Retry with backoff               |
| 502/503/504 | Unavailable  | Retry after delay                |

## Error Handling

1. Check HTTP status first; treat 4xx and 5xx appropriately.
2. Use the numeric **code** in the body for logic; see [Response Codes](../reference/response-codes.md).
3. Log **x-request-id** when present for support and debugging.
4. Retry only on 5xx or 429; fix 4xx requests before retrying.
5. Respect **Retry-After** on 429.