API Pagination, Errors, and Rate Limits

Every list endpoint in the Terminus Hub Public API returns the same pagination envelope, every error uses the same error object, and each API key has its own rate limit. Learn these three patterns once and handle them the same way across your integration.

Pagination

All list endpoints (GET /api/v1/workspaces, GET /api/v1/records, etc.) return a shared response envelope containing the page of results, a flag indicating whether more pages exist, and the total count of matching resources.

Query Parameters

Control pagination by passing the following query parameters on any list request:

integer

default:"1"

The page number to retrieve. Pages are 1-indexed. The first page is page=1. Omit this parameter to start from the beginning.

integer

default:"100"

The number of items to return per page, up to 10000. Defaults to 100 if not specified.

Example Paginated Request

The following request fetches the second page of workspaces, with 50 results per page:

curl "https://api.terminus.app/api/v1/workspaces?page=2&limit=50" \
  -H "Authorization: Bearer thub_xxxxx" \
  -H "Content-Type: application/json"

Pagination Response Envelope

Every list response wraps results in the same top-level envelope:

{
  "items": [
    {
      "id": "3f9a7c21-5b8e-4d6a-9c2f-1e7b4a8d6c30",
      "name": "EMEA Marketing",
      "description": "Campaigns for the EMEA region."
    }
  ],
  "has_more": true,
  "total_count": 142
}

array

required

The array of resource objects for the current page. Each item has the same shape as the endpoint’s single-item response. See each endpoint’s page for its schema and example.

boolean

required

true when there are additional pages beyond the current one. When false, the current page is the last page of results.

integer

required

The total number of resources matching the request’s filters, across all pages, not just the current page. Use this to calculate the total number of pages: ceil(total_count / limit).

To retrieve all results programmatically, increment page by 1 on each request and stop when has_more is false. Larger pages mean fewer requests; the maximum limit is 10000.

Errors

When a request fails, the API returns an appropriate HTTP status code and a JSON body containing a single error object. The structure is the same for every error type, so one error-handling function covers your whole integration. The one exception is a request with a missing or malformed Authorization header, described in Authentication errors.

Error Envelope

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "Workspace not found",
    "param": null,
    "path": null
  }
}

Error Response Fields

object

required

The top-level error container. All error details are nested inside this object.

Show error fields

enum

required

A broad category for the error. One of the types in the table below. Use this field to branch your error-handling logic.

string

required

A machine-readable code within the type category, such as missing_param or rate_limit_exceeded. It is never null: when an error has no finer-grained code, code is the default for its type (for example unauthenticated for a 401 or not_found for a 404, as listed in the table below). Suitable for programmatic handling or logging.

string

required

A human-readable description of the error explaining what went wrong. Suitable for displaying in logs or developer-facing UI, but not intended for end-user display.

string | null

required

When the error relates to a specific request parameter (e.g., a missing required field), this field names that parameter. null when the error is not tied to a specific input field.

string | null

A JSON pointer to the offending value inside the request body, when one is known. Public API requests have no body, so it is null on their errors, and 429 responses leave it out.

Error Types Reference

Type	HTTP Status	Default `code`	Description
`invalid_request_error`	422	`invalid`	The request was understood but a value is invalid, out of range, or fails a validation rule. Check the `param` field to identify the offending input. (A genuinely missing required parameter returns `400` with `code` set to `missing_param`.)
`authentication_error`	401	`unauthenticated`	The header starts with `Bearer thub_` but the key is not recognized, for example because it was mistyped or revoked. A missing or malformed header also returns `401`, with a different body. See Authentication.
`authorization_error`	403	`insufficient_permissions`	The API key is valid but the request is not allowed with an API key.
`not_found_error`	404	`not_found`	The requested resource does not exist. Verify the ID in the URL is correct and belongs to a resource your key can access.
`rate_limit_error`	429	`rate_limit_exceeded`	Too many requests have been made in a short period. Back off and retry after the delay in the `Retry-After` header.
`api_error`	5xx	`internal_error`	The server could not complete the request. These are rare. If they persist, contact Terminus Hub support.

The specification’s list of error types also includes plan_limit_exceeded, account_locked, and conflict_error. Those apply to requests that change data, so the read-only Public API endpoints do not return them.

Your integration should always check the HTTP status code first, then inspect error.type for branching logic, and error.code for fine-grained handling. Do not rely solely on error.message, as message text may change between API versions.

Handling Errors: Example

The snippet below shows a simple error-handling pattern in JavaScript:

const response = await fetch(
  "https://api.terminus.app/api/v1/records/rec_missing",
  {
    headers: { Authorization: "Bearer thub_xxxxx" },
  }
);

if (!response.ok) {
  const { error } = await response.json();

  switch (error.type) {
    case "authentication_error":
      console.error("Check your API key:", error.message);
      break;
    case "not_found_error":
      console.error("Resource not found:", error.message);
      break;
    case "rate_limit_error":
      console.warn("Rate limited, backing off...");
      // implement retry with exponential back-off
      break;
    default:
      console.error(`API error [${error.code}]:`, error.message);
  }
}

Rate limiting

Requests are rate limited per API key. Each key may make up to 100 requests per minute. Requests with no Authorization header are limited to 20 per minute per IP address. When you exceed the limit, the API responds with 429 and a rate_limit_error:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 42 seconds.",
    "param": null
  }
}

Every API-key response, successful or not, carries the X-RateLimit-* headers, so you can slow down before you hit the limit. A 429 adds Retry-After.

Header	Sent on	Meaning
`X-RateLimit-Limit`	Every response	The request ceiling for the window
`X-RateLimit-Remaining`	Every response	Requests left in the current window
`X-RateLimit-Reset`	Every response	Unix time when the window resets
`Retry-After`	`429` only	Seconds to wait before retrying

Respect Retry-After and use exponential back-off for resilient integrations.

Overview

Governance Models

Workspaces

Submissions

Records

Governance Models

Records

Submissions

Workspaces

API Pagination, Errors, and Rate Limits

Query Parameters

Example Paginated Request

Errors

Error Envelope

Error Response Fields

Error Types Reference

Handling Errors: Example

Rate limiting

​Pagination

​Query Parameters

​Example Paginated Request

​Pagination Response Envelope

​Errors

​Error Envelope

​Error Response Fields

​Error Types Reference

​Handling Errors: Example

​Rate limiting

Pagination

Query Parameters

Example Paginated Request

Pagination Response Envelope

Errors

Error Envelope

Error Response Fields

Error Types Reference

Handling Errors: Example

Rate limiting