Skip to main content

​
Error envelope

Authenticated errors use a stable JSON envelope: 
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  },
  "requestId": "req_123"
}
Use requestId when working with Trailflow support.

​
Common status and error codes

The Partner API currently returns these common combinations:
  • 400 bad_request
  • 400 missing_idempotency_key
  • 401 unauthorized
  • 403 forbidden
  • 403 partner_access_not_enabled
  • 403 live_access_not_enabled
  • 403 partner_access_disabled
  • 404 not_found
  • 409 idempotency_conflict
  • 409 idempotency_in_progress
  • 429 rate_limited
  • 500 internal_error

​
Rate limits

Each API client has a server-enforced per-minute rate limit. Current operating range:
  • default issuance target: 60 requests per minute
  • allowed configured range: 1 to 600 requests per minute
The API may return 429 rate_limited before idempotent replay lookup, so duplicate write requests are not guaranteed to bypass rate limiting.

​
Retry guidance

Recommended partner behavior:
  • retry only when the status code and workflow make retry safe
  • reuse the same Idempotency-Key when retrying a failed write request with the same body
  • avoid tight retry loops after 429 responses
  • capture requestId, route, and timestamp before escalating support issues

​
Webhook failures

Webhook deliveries treat network failures and non-2xx responses as failures. Retries are bounded, and replay is coordinated with Trailflow after the partner confirms remediation.