Errors

All errors return a JSON body with the same shape:

{
  "error_code": "not_found",
  "message": "Connection 'conn_123' not found.",
  "details": { ... }
}

details is optional and present when there is structured context (e.g. missing scopes, validation fields).

Error codes

HTTP	`error_code`	Description
400	`bad_request`	Invalid request.
400	`provider_not_supported`	The requested provider is not supported.
400	`oauth_state_invalid`	OAuth state parameter is missing or invalid.
401	`authentication_error`	Invalid or missing credentials.
403	`permission_denied`	Authenticated but lacks the required permission.
403	`insufficient_scopes`	API key is missing required scopes. `details.missing_scopes` lists them.
404	`not_found`	Resource not found.
404	`connection_not_found`	Connection not found.
404	`client_not_found`	Client not found.
409	`conflict`	Request conflicts with existing state.
422	`unprocessable_entity`	Request body failed validation.
429	`rate_limit_exceeded`	Rate limit exceeded.
500	`internal_server_error`	Unexpected server error.
502	`upstream_error`	A downstream dependency returned an error.
502	`oauth_provider_error`	OAuth provider returned an error.
502	`knowledge_engine_error`	Knowledge engine returned an error.
503	`knowledge_engine_unavailable`	Knowledge engine is not available.