Errors and pagination

Errors

Every error comes back in the same JSON envelope:

{
  "success": false,
  "status": "fail",
  "statusCode": 404,
  "error": "Customer not found",
  "code": "NOT_FOUND",
  "requestId": "254170de-2cc0-4c8b-aec8-d280f3710f98"
}

Field	Meaning
statusCode	The HTTP status, repeated
status	fail for a problem with the request (4xx), error for a server problem
error	A human-readable message. For an unexpected 500 it's a generic message
code	VALIDATION, NOT_FOUND, UNAUTHORIZED, FORBIDDEN, CONFLICT or INTERNAL. Some 400s have none
requestId	Quote this when you contact CloudERM support about a failed request
details	Extra structured context. Present only when an endpoint provides it

The statuses you'll see most:

Status	When
400	The request body or parameters are invalid; error says which. Some endpoints also use 400 for a record that doesn't exist
401	Not authenticated, or the credential's role lacks the endpoint's permission; error says which. See Authentication
403	Refused for a reason other than a missing permission; error says why
404	The record doesn't exist, or isn't visible to you
409	A conflict, such as a duplicate name
500	A server error. If a retry fails too, contact support with the requestId

Pagination

List and search endpoints take a paginate object in the request body:

{ "paginate": { "currentPage": 1, "perPage": 25 } }

currentPage starts at 1. perPage is 1 to 100. Both are required when paginate is sent, and unknown keys are refused. Whether paginate itself is required depends on the endpoint.

The response carries a page block next to the rows. Its keys differ between lists. On many lists, total, lastPage, prevPage and nextPage come back on page 1 only, so read the total from the first page and keep requesting until a page has fewer rows than perPage. Each endpoint in the API reference describes its own page block.