# Errores, límites y paginación

> Estados HTTP de error, límites de solicitudes por api key, encabezados X-RateLimit y paginación por limit y offset.

URL canónica: https://apis.cortecloud.com.br/docs/es/comecando/erros-limites-paginacao/

## Errores {#erros}

| Estado | Situación |
| --- | --- |
| `400` | El cuerpo o la query string no pasó la validación de la ruta (campo obligatorio ausente, tipo incorrecto, valor fuera de lo permitido). |
| `401` | Falla de autenticación. Las causas están en [Autenticación](https://apis.cortecloud.com.br/docs/es/comecando/autenticacao.md#quando-a-autenticacao-falha). |
| `403`, `404`, `409`, `422` | Error de negocio de la ruta: recurso no encontrado, estado del servicio que no permite la operación, vendedor inexistente, central sin permiso. Cada guía enumera los errores de sus rutas, y la [Referencia de la API](https://apis.cortecloud.com.br/docs/swagger) trae la descripción de cada operación. |
| `429` | Su integración superó el [límite de solicitudes](https://apis.cortecloud.com.br/docs/es/comecando/erros-limites-paginacao.md#limites-de-requisicao). |
| `5xx` | Falla al procesar la solicitud en Serrabits, incluido `504` cuando la respuesta supera el tiempo límite. Puede ser transitoria: reintente con espera creciente y un número limitado de intentos, y escriba a suporte@serrabits.com.br si persiste. |

Algunas rutas también responden `500` o `502` cuando Cortecloud rechaza la operación; en esos casos, repetir no lo resuelve, y la guía de la ruta indica qué corregir. El cuerpo de la respuesta de error trae un mensaje con el motivo. Use el estado HTTP para decidir el tratamiento y el mensaje para registrar y diagnosticar.

## Límites de solicitudes {#limites-de-requisicao}

Los límites son por api key y se cuentan por separado en cada ruta:

- **5 solicitudes por segundo** en la mayoría de las rutas.
- **1 solicitud cada 5 segundos** en las rutas que operan sobre la colección entera:
  - listado y actualización en lote de materiales: `GET`, `PUT` y `PATCH` en `/materials/boards`, `/materials/edges` y `/materials/components`;
  - copia entre centrales: `POST /materials/boards/cross-sync`, `POST /materials/edges/cross-sync` y `POST /materials/components/cross-sync`;
  - listado de servicios: `GET /services`.

Cada respuesta trae los encabezados:

| Encabezado | Contenido |
| --- | --- |
| `X-RateLimit-Limit` | Cuántas solicitudes acepta la ruta en la ventana. |
| `X-RateLimit-Remaining` | Cuántas quedan todavía en la ventana actual. |
| `X-RateLimit-Reset` | Segundos hasta que la ventana se reinicie. |

Por encima del límite, la respuesta es `429` con `Retry-After` en segundos. Espere ese tiempo antes de repetir la solicitud. Trate `429` por separado de los errores de negocio: la solicitud no fue procesada y puede repetirse sin efectos secundarios.

Al recorrer un listado paginado en una ruta de 1 solicitud cada 5 segundos, espere entre una página y la siguiente. Para actualizar muchos materiales, prefiera una llamada en lote a varias llamadas individuales.

## Paginación {#paginacao}

Los listados (`GET /services`, `GET /materials/boards`, `GET /materials/edges`, `GET /materials/components`) aceptan `limit` y `offset` en la query string:

- `limit`: ítems por página, como máximo `500`; el valor predeterminado también es `500`.
- `offset`: cuántos ítems omitir; el valor predeterminado es `0`.

La respuesta trae los ítems en `resource` y la paginación en `meta`:

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

Para la página siguiente, envíe en `offset` el valor de `meta.next` de la respuesta anterior. `meta.next` nulo indica la última página.

## Antes de pasar a producción {#antes-de-ir-para-producao}

- La secret key está guardada solo en su backend.
- Su firma reproduce los [ejemplos de validación](https://apis.cortecloud.com.br/docs/es/comecando/autenticacao.md#valide-a-sua-implementacao).
- Cada solicitud envía `x-company-internal-code`.
- La integración lee los encabezados `X-RateLimit-*` y trata `429` por separado de los errores de negocio.
- Los listados siguen `meta.next` hasta que llegue nulo.