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

# Errors and limits

> Planned error, pagination, idempotency, and rate-limit categories for the Woes public API.

Public API integrations need predictable failure behavior. This page describes the error and limit categories Woes should document before endpoint-level release.

## Planned error categories

| Category                   | Typical meaning                                                   |
| -------------------------- | ----------------------------------------------------------------- |
| Authentication failed      | The credential is missing, invalid, expired, or revoked.          |
| Permission denied          | The credential is valid but lacks the required scope.             |
| Workspace not found        | The workspace is missing or not visible to the credential.        |
| Resource not found         | The requested object does not exist in the workspace.             |
| Validation failed          | The request shape or field value is invalid.                      |
| Payload too large          | The request body exceeds accepted limits.                         |
| Rate limited               | The integration sent too many requests.                           |
| Conflict                   | The requested state change conflicts with current resource state. |
| Idempotency conflict       | The same idempotency key was reused with different content.       |
| Upstream unavailable       | A dependent provider or integration is unavailable.               |
| Source scan failed         | API Context ingestion could not complete.                         |
| Agent context insufficient | The agent cannot answer from available evidence.                  |

## Planned limit categories

<CardGroup cols={2}>
  <Card title="Payload limits" icon="file-warning">
    Maximum body size and file/source upload limits.
  </Card>

  <Card title="Pagination" icon="list">
    Page size, cursors, ordering, and filtering boundaries.
  </Card>

  <Card title="Rate limits" icon="gauge">
    Per-credential, per-workspace, or per-route request limits.
  </Card>

  <Card title="Webhook delivery" icon="webhook">
    Timeout, retry, and payload-size expectations.
  </Card>

  <Card title="Source ingestion" icon="database">
    Crawl, document, chunk, and scan limits.
  </Card>

  <Card title="Live verification" icon="activity">
    Guardrails for running API checks from Woes.
  </Card>
</CardGroup>

## Retry guidance

Future endpoint docs should state:

* Which errors are safe to retry.
* Which errors require user action.
* Which operations support idempotency keys.
* How rate-limit reset information is returned.
* How webhook retries are scheduled.

## Current expectation

Rate limits should be treated as practical product controls, not a full DDoS or compliance boundary. Teams with high-volume integration needs should coordinate capacity and monitoring before launch.