API Error Model

Error Response Format

{
  "detail": "Human-readable error message"
}

For validation errors (422), the response includes field-level details:

{
  "detail": [
    {
      "loc": ["body", "flow_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Status Codes

Code	Meaning	When It Occurs
200	OK	Successful GET, PATCH, DELETE, and most POST requests
201	Created	Resource successfully created (some POST endpoints)
400	Bad Request	Invalid request body, missing required fields, or invalid parameter values
401	Unauthorized	Missing, invalid, or expired authentication token
403	Forbidden	Authenticated but insufficient permissions (RBAC)
404	Not Found	Requested resource does not exist, or protected environment deletion attempted
409	Conflict	Resource already exists (e.g., duplicate secret name, duplicate schedule ID)
422	Unprocessable Entity	Request body fails Pydantic validation
429	Too Many Requests	Rate limit exceeded or usage quota exceeded
500	Internal Server Error	Unexpected server error (configuration issue, database failure, etc.)

Common Error Scenarios

Authentication Errors (401)

{
  "detail": "Invalid or expired access token"
}

Occurs when the Authorization header is missing, the token is expired, or the token is invalid.

Permission Errors (403)

{
  "detail": "Permission denied: flows.write required"
}

Occurs when the authenticated user's role lacks the required permission for the endpoint. See the RBAC documentation for the permission matrix.

Rate Limiting (429)

{
  "detail": "Rate limit exceeded"
}

Response headers include:

• Retry-After: 12: Seconds to wait before retrying
• X-RateLimit-Limit: 120: Maximum requests per minute
• X-RateLimit-Remaining: 0: Remaining requests in window

Quota Exceeded (429)

{
  "detail": "Monthly run quota exceeded. Current: 100/100. Upgrade plan at /billing/plans"
}

Occurs on POST /runs when the organization has exceeded its plan's usage limits. Check GET /usage/quota for current usage vs limits.

Resource Not Found (404)

{
  "detail": "Run abc123 not found"
}

Also returned when attempting to delete a protected environment:

{
  "detail": "Environment 'production' is protected and cannot be deleted"
}

Validation Errors (422)

{
  "detail": [
    {
      "loc": ["body", "mode"],
      "msg": "value is not a valid enumeration member; permitted: 'cron', 'interval', 'one_time', 'manual'",
      "type": "type_error.enum"
    }
  ]
}

Error Handling Best Practices

1. Always check status codes: Don't assume 200; handle 4xx and 5xx appropriately
2. Retry on 429: Use the Retry-After header to determine wait time
3. Retry on 5xx: Server errors may be transient; use exponential backoff
4. Don't retry 4xx: Client errors (except 429) indicate a problem with the request
5. Log error details: The detail field provides actionable information
6. Handle quota errors gracefully: Check GET /usage/quota before triggering runs in bulk