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

# Responses, pagination, and retries

> Read the response shape for the endpoint you call.

Most endpoints return `success`, `data`, and a `timestamp` in epoch milliseconds.
Errors commonly contain an `error` object with a stable `code` and a `message`.
Some endpoints use a different shape; the operation's API reference is the contract.

## Read every page

Cursor-based lists return `data`, `has_more`, and `next` at the top level. Send `next`
back as the next request's query parameter, preserving the other filters:

```bash theme={null}
curl --fail-with-body --get 'https://api.gigstack.io/v2/clients' \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  --data-urlencode 'limit=10' \
  --data-urlencode 'next=CURSOR_FROM_PREVIOUS_RESPONSE'
```

Stop when `has_more` is false. The usual default limit is 10, with a maximum of 100.
Search, SAT catalogs, and some metadata-filtered lists use page-based pagination instead.
For example, catalog searches return `found`, `page`, and `per_page`; do not look for a
`next` cursor in that response. Check the endpoint before writing a pagination loop.

## Handle errors deliberately

| Status | Next action |
| - | - |
| `400` | Read the error code. Fix validation fields; `resource_conflict` can instead mean a payment or receipt already exists. |
| `401` | Check the key and the `Bearer ` prefix. |
| `403` | Check team access, mode, role, and plan permissions. |
| `404` | Check the resource ID and the team and mode it belongs to. |
| `409` | Read the conflict before deciding whether to retry. |
| `429` | Identify the limit. Document credits and daily quotas may need action or a reset. |
| `500`, `503` | Retry reads with bounded exponential backoff; reconcile writes first. |

## Avoid duplicate writes

A timeout does not prove a write failed. Look up the result before repeating a creation,
stamping, payment, or refund request. Use an idempotency key only where the endpoint documents
one; gigstack does not promise a universal idempotency header.

For callbacks, use the [webhook guide](/guides/webhooks). Event formats, signatures, and retry
behavior differ between resource events and SAT synchronization events.

See [real error examples](/troubleshooting) and [verification coverage](/verification).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.