# Errors, limits and pagination

> HTTP error statuses, per-api-key request limits, X-RateLimit headers and limit/offset pagination.

Canonical URL: https://apis.cortecloud.com.br/docs/en/comecando/erros-limites-paginacao/

## Errors {#erros}

| Status | Situation |
| --- | --- |
| `400` | The body or the query string failed the route's validation (required field missing, wrong type, value outside the allowed range). |
| `401` | Authentication failure. The causes are listed in [Authentication](https://apis.cortecloud.com.br/docs/en/comecando/autenticacao.md#quando-a-autenticacao-falha). |
| `403`, `404`, `409`, `422` | Business error of the route: resource not found, service status that does not allow the operation, nonexistent salesperson, service center without permission. Each guide lists the errors of its routes, and the [API reference](https://apis.cortecloud.com.br/docs/swagger) has the description of each operation. |
| `429` | Your integration exceeded the [request limit](https://apis.cortecloud.com.br/docs/en/comecando/erros-limites-paginacao.md#limites-de-requisicao). |
| `5xx` | Serrabits failed to process the request, including `504` when the response exceeds the time limit. It may be transient: retry with increasing backoff and a limited number of attempts, and write to suporte@serrabits.com.br if it persists. |

Some routes also respond with `500` or `502` when Cortecloud rejects the operation; in these cases retrying does not help, and the route's guide says what to fix. The error response body carries a message with the reason. Use the HTTP status to decide how to handle it and the message to log and diagnose.

## Request limits {#limites-de-requisicao}

Limits are per api key and counted separately for each route:

- **5 requests per second** on most routes.
- **1 request every 5 seconds** on routes that operate on the whole collection:
  - listing and batch update of materials: `GET`, `PUT` and `PATCH` on `/materials/boards`, `/materials/edges` and `/materials/components`;
  - copy between service centers: `POST /materials/boards/cross-sync`, `POST /materials/edges/cross-sync` and `POST /materials/components/cross-sync`;
  - listing of services: `GET /services`.

Every response carries the headers:

| Header | Content |
| --- | --- |
| `X-RateLimit-Limit` | How many requests the route accepts in the window. |
| `X-RateLimit-Remaining` | How many are left in the current window. |
| `X-RateLimit-Reset` | Seconds until the window restarts. |

Above the limit, the response is `429` with `Retry-After` in seconds. Wait that long before retrying the request. Handle `429` separately from business errors: the request was not processed and can be retried without side effects.

When walking through a paginated listing on a route limited to 1 request every 5 seconds, wait between one page and the next. To update many materials, prefer one batch call over several individual calls.

## Pagination {#paginacao}

The listings (`GET /services`, `GET /materials/boards`, `GET /materials/edges`, `GET /materials/components`) accept `limit` and `offset` in the query string:

- `limit`: items per page, at most `500`; the default is also `500`.
- `offset`: how many items to skip; the default is `0`.

The response carries the items in `resource` and the pagination in `meta`:

```json
{
  "resource": [],
  "meta": {
    "count": 1234,
    "next": 500
  }
}
```

For the next page, send the value of `meta.next` from the previous response in `offset`. A null `meta.next` indicates the last page.

## Before going to production {#antes-de-ir-para-producao}

- The secret key is stored only in your backend.
- Your signature reproduces the [validation examples](https://apis.cortecloud.com.br/docs/en/comecando/autenticacao.md#valide-a-sua-implementacao).
- Every request sends `x-company-internal-code`.
- The integration reads the `X-RateLimit-*` headers and handles `429` separately from business errors.
- Listings follow `meta.next` until it comes back null.