API Errors and Retries

API Errors and Retries

Every v1 response uses the same envelope. Preserve meta.requestId in logs and support requests so a failed call can be traced.

Error envelope

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "details": {}
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2026-08-04T10:00:00.000Z"
  }
}

Important status codes

Retry matrix

Generally safe to retry:

• GET requests
• Schema reads and workflow previews
• Direct read-only SQL when duplicate execution is acceptable
• 429 and transient 5xx responses after backoff

Do not blindly retry:

• POST /api/v1/workflows/{id}/actions/{order}/test
• POST /api/v1/workflows/{id}/run
• Webhook test deliveries
• Credential rotation
• Resource creation when the first response outcome is unknown

These calls may have completed even when the caller did not receive a successful response.

External API acceptance

Webhook actions consider 2xx successful by default. Set successStatusCodes when a provider uses different 2xx codes for full and partial acceptance. For Brevo batch events, [202] treats HTTP 207 as a visible failure so partial acceptance is not reported as success.

Pagination

List endpoints use page and pageSize. Continue until page >= totalPages. Do not assume cursor pagination.

Rate limits

Rate limits are enforced per organization: