---
title: "Requests, responses, errors, and correlation IDs"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/request-conventions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Requests, responses, errors, and correlation IDs

The conventions every client should apply for JSON, pagination, safe errors, retries, and operational evidence.

## In brief

- **Format:** JSON over HTTPS
- **Page size:** 1–100 for record search
- **Evidence:** Correlation ID

Use the generated OpenAPI operation and schema as the exact contract. The rules below are the cross-cutting behavior a production client should implement once and reuse for every operation.

## Headers and content

- Send the credential as `Authorization: Bearer <credential>`.
- Send JSON request bodies as `application/json`.
- Retain the server-issued `X-Correlation-ID` from each response. A caller-supplied value is an untrusted hint and is not echoed as the server's audit identity; use supported W3C trace context for cross-service tracing.
- Never log authorization headers, secret references, OAuth codes, webhook secrets, or full sensitive payloads.

## Pagination and bounds

Record search uses one-based `page` and a bounded `pageSize` from 1 through 100. Query text is bounded to 400 characters. Other list endpoints expose their own limits in OpenAPI; do not assume one pagination shape fits every resource.

## Safe error handling

| Status | Client behavior |
| --- | --- |
| `400` | Fix validation or request shape; do not retry unchanged input. |
| `401` | Resolve or rotate the credential; never fall back to a broader credential automatically. |
| `403` / safe `404` | Do not probe for cross-app existence. Verify app binding and required scope. |
| `409` | Reload current state and resolve the concurrency or lifecycle conflict. |
| `422` | Show the domain, plan, or policy failure to an operator. |
| `429` | Honor `Retry-After` and back off with jitter. |
| `5xx` | Retry only safe/idempotent work, with a bounded backoff and the same logical request key where supported. |

## Do not parse internal diagnostics

Error responses provide a stable contract version, safe code/message, and correlation ID. Database names, stored procedures, server paths, provider secrets, and stack traces are deliberately absent. Treat wording as human-readable context and branch on documented codes/status instead.

Tip

A useful integration log entry contains the operation ID, app ID, HTTP status, duration, and correlation ID—never the bearer credential or a raw secret.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/request-conventions.html).