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

# Authentication and retries

> Protect API keys and retry requests safely.

## Bearer authentication

Send the API key in every request:

```bash theme={null}
curl https://api.mint.gg/v1/me \
  -H "Authorization: Bearer $MINT_API_KEY"
```

API keys are server-side secrets. Never expose them in browser JavaScript, mobile bundles, public repositories, logs, analytics, or prompts. Rotate a key if it may have leaked.

`GET /v1/me` identifies the API key and the Mint account that owns it. Assets created with the key belong to that account and can be read through supported API, MCP, and Mint surfaces.

## Rate limits

Mint uses continuously refilling account-level limits. All API keys owned by the same Mint account share these limits.

| Traffic                                                                              | Limit                   |
| ------------------------------------------------------------------------------------ | ----------------------- |
| Authenticated API requests, including reads and operation polling                    | 600 requests per minute |
| Generation starts and paid approve, revise, retry, derivative, and animation actions | 30 requests per minute  |
| 3D Model conversions                                                                 | 30 requests per minute  |

The general request limit and a paid-work limit apply together when both are relevant. Successful responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` for the active bucket. `X-RateLimit-Reset` is the Unix timestamp when the continuously refilling bucket should be full again.

A `429 Too Many Requests` response includes the same rate-limit headers plus `Retry-After`; wait at least that long before retrying. Use bounded polling rather than a tight loop.

These limits protect the service without restricting ordinary integrations. Contact Mint before intentionally scheduling sustained traffic near a limit.

## Retry policy

Retry connection failures, `429`, and retryable `5xx` responses with exponential backoff and jitter. Respect `Retry-After` when present. Do not blindly retry validation, authentication, payment, or conflict responses.

A `400` validation problem can report up to five invalid fields in `errors`. Each entry includes a field `path`, validation `code`, and readable `message`. Correct every listed field before sending the request again.

```json theme={null}
{
  "type": "https://api.mint.gg/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "body.prompt: String must contain at least 1 character",
  "errors": [
    {
      "path": "body.prompt",
      "code": "too_small",
      "message": "String must contain at least 1 character"
    }
  ]
}
```

Every API response includes `X-Request-Id`. Save it with failed-request logs and include it when contacting Mint support. Problem `type` URLs are stable public error categories; branch on the complete URL rather than matching prose in `detail`.

For ordinary mutations, Mint creates an internal request key automatically. You do not need to send another header.

## Optional retry protection

If your application will retry a mutation when it cannot tell whether Mint accepted the original request, send an optional `Idempotency-Key`. Generate one stable key before the first attempt and reuse it only for retries of that same request.

```bash theme={null}
export MINT_RETRY_KEY="$(uuidgen)"

curl https://api.mint.gg/v1/models:generate \
  -X POST \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $MINT_RETRY_KEY" \
  -d '{
    "prompt": "A hand-painted treasure chest",
    "generationPreset": "fast"
  }'
```

The same key and request return the existing operation. The same key with different input returns a conflict. Retrying without a caller-supplied key can start another operation when the first response was lost.

Some actions also protect the asset's current state. Approving Asset Pack items that already started returns their current work without another charge. Repeating the same optimization level does not create another optimized copy. Smart topology and animation create additional outputs, so retry an uncertain request only with the stable key supplied on its first attempt.