Errors, limits and pagination

Errors

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.
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 has the description of each operation.
429	Your integration exceeded the request limit.
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

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

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:

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

• The secret key is stored only in your backend.
• Your signature reproduces the validation examples.
• 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.