Developer Platform
Requests, responses, errors, and correlation IDs
The conventions every client should apply for JSON, pagination, safe errors, retries, and operational evidence.
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. - Generate a fresh correlation ID for each logical operation when the client supports it, and retain the response correlation ID in logs.
- 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.
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.