> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/developers/data-api/authentication-and-limits.md).

# Authentication & Limits

## Authentication

Every Market Data API request must include the API key in this header:

```http
x-soso-api-key: YOUR_API_KEY
```

API keys are issued from the [SoSoValue Developer Dashboard](https://sosovalue.com/developer/dashboard). Keep keys on a trusted server, store them securely, and rotate any key that may have been exposed.

## Request limits

Limits are applied per API key:

| Dimension         | Limit                  |
| ----------------- | ---------------------- |
| Monthly quota     | 100,000 requests       |
| Request frequency | 20 requests per minute |

The API reports the current minute window in these response headers:

| Header                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests in the current window                |
| `X-RateLimit-Remaining` | Requests remaining in the current window              |
| `X-RateLimit-Reset`     | Window reset time as a Unix timestamp in milliseconds |

## Handling rate limits

When the request frequency is exceeded, the API returns `429 Too Many Requests`:

```json
{
  "code": 42901,
  "message": "Rate limit exceeded",
  "details": {
    "limit": 20,
    "window": "60s",
    "retry_after": 45
  }
}
```

Wait for the indicated retry interval before sending another request. Use the rate-limit headers to throttle requests before the limit is reached.

## Common HTTP errors

| HTTP status | Meaning                                               |
| ----------- | ----------------------------------------------------- |
| `400`       | A required parameter is missing or invalid            |
| `401`       | The API key is invalid or expired                     |
| `403`       | The API key does not have permission for the endpoint |
| `404`       | The requested resource or endpoint was not found      |
| `429`       | The request limit was exceeded                        |
| `500`       | The service encountered an internal error             |
| `503`       | The service is temporarily unavailable                |

Error responses include a machine-readable `code`, a `message`, and, when available, a `details` object with information about the failure.

## Inspect response headers

```bash
curl -sS -i https://openapi.sosovalue.com/openapi/v1/currencies \
  -H "x-soso-api-key: $SOSO_API_KEY" \
  -H 'Accept: application/json'
```

Set `SOSO_API_KEY` to your approved key. Inspect the HTTP status and rate-limit headers before sending further requests.