Pagination and errors

Every paginated endpoint returns the same pagination structure, and all errors use the same response format.

Pagination shape

{
  "pagination": {
    "page": 1,
    "page_size": 100,
    "has_next_page": false
  }
}
  • page is the current page number.
  • page_size is the fixed number of records returned per page.
  • has_next_page tells you whether another request should be made with the next page number.

Error format

All error responses use the same structure:

{
  "error": {
    "code": "invalid_argument",
    "message": "Request parameters are invalid."
  }
}

Error codes

  • method_not_allowed
  • unauthorized
  • forbidden
  • not_found
  • invalid_argument
  • failed_precondition
  • internal

Handling guidance

  • Normalize error handling around error.code first, then log the human-readable message.
  • Treat validation and auth failures as non-retryable until the request is fixed.
  • Continue paginating only while has_next_page is true.