# Limits

## Rate Limits

All Skribble APIs enforce rate limiting. Exceeding a limit returns `429 Too Many Requests`. Requests resume once the rate limit window resets.

:::info

Specific numeric limits (requests per minute/hour) are not published in the OpenAPI specs. Contact [info@skribble.com](mailto:info@skribble.com) if you need exact thresholds for capacity planning.

:::

### General Behaviour

Every endpoint can return a `429` response. When you receive one:

1. **Stop sending requests** to that endpoint immediately.
2. **Check the `Retry-After` header** (if present); it indicates how many seconds to wait.
3. **Back off exponentially** if no header is present (e.g. 1 s → 2 s → 4 s → …).
4. **Retry** once the wait period has elapsed.

### Known Per-Endpoint Limits

| Endpoint | Limit |
|----------|-------|
| `POST /access/login` | Rate limited; avoid re-authenticating on every request; cache tokens for their ~20-minute lifetime. |
| `POST /signature-requests/{id}/remind` | **One reminder per signer per hour.** The API enforces this server-side; exceeding it returns `429`. Track reminder timestamps client-side to avoid unnecessary calls. |

### Recommended Client Behaviour

```js
async function requestWithBackoff(fn, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fn();

    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get('Retry-After') || 0);
    const wait = retryAfter > 0 ? retryAfter * 1000 : Math.pow(2, attempt) * 1000;
    await new Promise(r => setTimeout(r, wait));
  }

  throw new Error('Rate limit retries exhausted');
}
```

## Document Size Limits

### Sign API

| Constraint | Limit |
|------------|-------|
| Documents per signature request | 50 |
| Max document size (unencoded) | 112.5 MB |
| Max document size (Base64 encoded) | 150 MB |

Documents must be Base64-encoded when sent to the API. Base64 introduces a size overhead of approximately 33%:

```
unencoded × 4/3 = encoded size
e.g. 112.5 MB × 4/3 = 150 MB
```

Ensure your document does not exceed **112.5 MB** before encoding.

### Validation API

| Constraint | Limit |
|------------|-------|
| Document size (multipart upload) | 50 MB |
| Document size (Base64 JSON payload) | 50 MB (Base64 overhead is handled automatically) |
| Request size | 50 MB |

### Attachments

There is currently no documented limit on the number of attachments per signature request. Abusive usage may result in enforced limits.

## Performance Tips

1. **Batch document uploads**: Upload documents in parallel before creating requests
2. **Cache authentication tokens**: Reuse tokens until they expire
3. **Use pagination**: When listing requests, use `page_number` and `page_size`
4. **Poll efficiently**: Use callbacks instead of polling when possible