API Pagination, Error Handling & Response Shapes

Every list endpoint in the Terminus Hub Public API returns results using a consistent pagination envelope, and every error (regardless of the endpoint or failure reason) uses the same error object structure. Learning these two patterns once means you can handle them uniformly across your entire 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. Must be between 1 and 10000 (inclusive). Defaults to 100 if not specified.

Example Paginated Request

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

curl "https://hub.terminus.app/api/v1/records?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": "9b2c1f4e-7a3d-4c8e-9f1a-2b6d5e4c3a10",
      "status": "active",
      "terminus_id": "trm0kf8m2a1q",
      "data": {}
    }
  ],
  "has_more": true,
  "total_count": 142
}

array

required

The array of resource objects for the current page. The shape of each item depends on the endpoint (Workspace, Record, Submission, etc.).

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 identical regardless of the error type, making it easy to write a single error-handling function for your entire integration.

Error Envelope

{
  "error": {
    "type": "not_found_error",
    "code": null,
    "message": "Record 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: invalid_request_error, authentication_error, authorization_error, not_found_error, rate_limit_error, plan_limit_exceeded, or api_error. Use this field to branch your error-handling logic.

string | null

required

A specific, machine-readable code within the type category when one applies (e.g., missing_param, feature_required, limit_exceeded, rate_limit_exceeded), or null when the error has no finer-grained code (most authentication and not-found errors). 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

required

When the error points at a specific location inside the request body, this field holds a path to it. null when not applicable.

Error Types Reference

Type	HTTP Status	Description
`invalid_request_error`	422	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`.)
`authentication_error`	401	The API key is missing, incorrectly formatted, or has been revoked. See Authentication for guidance.
`authorization_error`	403	The API key is valid but does not have permission to access the requested resource. Verify the key belongs to an account with the necessary access.
`not_found_error`	404	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	Too many requests have been made in a short period. Back off and retry after the delay in the `Retry-After` header.
`plan_limit_exceeded`	422	The request needs a feature or exceeds a limit not included in your current plan. Check `param` for the feature or resource, then upgrade to proceed.
`api_error`	500	An unexpected error occurred on the Terminus Hub server. These are rare. If they persist, contact Terminus Hub support.

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 demonstrates a simple, robust error-handling pattern in JavaScript:

const response = await fetch(
  "https://hub.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. (Unauthenticated requests are limited to 20 per minute per IP.) 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 429 includes headers to help you back off:

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

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

Overview

Governance Models

Workspaces

Submissions

Records

Governance Models

Records

Submissions

Workspaces

API Pagination, Error Handling & Response Shapes

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