API Response Contract

All JSON API endpoints follow a standardized envelope:

• Success:
• { "success": true, "error": null, "data": <payload> }
• Error:
• { "success": false, "error": { "code": "...", "message": "...", "details": ..., "request_id": "..." }, "data": null }

Status Codes

• 200/201/202/204: successful operations
• 400: malformed request semantics
• 401: unauthenticated request
• 403: unauthorized request
• 404: resource not found
• 409: conflict
• 422: schema validation failures
• 429: rate-limited request
• 500: unhandled internal error
• 502/504: upstream dependency failures and timeouts

Validation

• FastAPI request body, query, and path validation is schema-first via Pydantic models.
• Validation failures return 422 with error.details.

Compatibility Exceptions

The following endpoints keep protocol-specific response shapes:

• SAML endpoints (/v1/auth/saml/*) keep XML/redirect wire contracts.
• SCIM endpoints (/v1/scim/*) keep SCIM-compatible media types and schemas.
• Interactive webhook callbacks (/integrations/slack/interactions, /v1/webhooks/slack/interactions, /v1/webhooks/teams/interactions) keep provider-required callback payloads.

All other JSON endpoints are normalized through shared contract middleware and global exception handling.