Errores, límites y paginación

Errores

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.
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 trae la descripción de cada operación.
429	Su integración superó el límite de solicitudes.
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

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

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:

{
  "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

• La secret key está guardada solo en su backend.
• Su firma reproduce los ejemplos de validación.
• 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.