---
title: WGO Authentication, Limits, and Errors
description: Bearer-token scope, default request limit, error handling, and security guidance for the WGO API.
---

# Authentication, limits, and errors

## Bearer token

Every `/api/wgo/v1/` request requires:

```http
Authorization: Bearer mq_xxx
```

The token must authorize the `wgo:read` scope. A missing token, an invalid, expired,
or revoked token, and a token without that scope all return `401`.

Apply for or manage a token through the [MobiusQuant token guide](/token). The API's
internal collection credential is unrelated and is never used by read clients.

## Rate limit

The WGO default is 60 requests per minute per token. A token-specific limit can be
lower, so clients must treat `429` as authoritative and wait for the number of seconds
in `Retry-After`.

For daily reporting, prefer one overview call per asset, then request historical or
per-fund details only when needed.

## Errors

| HTTP | Meaning | Client action |
| --- | --- | --- |
| `401` | Token missing, invalid, expired, revoked, or lacks `wgo:read` | Fix the token; do not retry unchanged |
| `422` | Invalid asset, date, range, or limit | Read `detail` and correct the request |
| `429` | Token request limit exceeded | Honor `Retry-After` |
| `500`–`503` | Service or database temporarily unavailable | Retry with bounded exponential backoff |

An empty valid query returns `200` with an empty `data` array, or an overview with
`observations: 0`; it is not a `404`.

## Date-range validation

Dates use `YYYY-MM-DD`. If both `start` and `end` are supplied, `start` must not be
after `end`.

```json
{
  "detail": "start must not be after end"
}
```

## Security

- Store tokens in environment variables or a secret manager.
- Use a separate token for each environment.
- Never publish a token in documentation, logs, source control, or client-side JavaScript.
- Revoke and replace a token immediately if it may have leaked.

## API contract

- [Interactive Swagger](https://api.mobiusquant.ai/api/wgo/docs)
- [Live OpenAPI](https://api.mobiusquant.ai/api/wgo/openapi.json)
- [Validated documentation snapshot](/wgo/openapi.json)

The documentation build validates the public path and parameter inventory against the
live OpenAPI schema. Internal collection routes are excluded from the public contract.