connection_failed

The gateway could not establish a network connection to the database server (for example, connection refused).

Verify server_address (host and port) is correct and reachable from the gateway. Check firewall and security group rules between the gateway and the database. Confirm the database server is running and accepting connections.

external_integration_error

The database instance returned an error 

Review the message field for the specific database-reported error. Resolve the reported condition on the database instance, then retry the request.

Check the database instances’s own logs for the matching entry if you need more detail than the message field provides.

insufficient_permissions

The integration user does not have all the privileges OPA requires 

Look at the message field to see the missing privileges.

Grant the missing privilege(s) to the integration user and then retry. See Database integration user privileges.

integration_already_exists

The connection collides with an existing integration in this team.

Review the message field to identify the collision, then list the team's connections with `GET /teams/{team}/connections/databases` to find the conflicting integration. 

The collision is one of the following:

- Duplicate name:  Another connection in the team already uses this name. Retry with a different name.

- Same primary identifier: This database instance is already integrated. Reuse the existing connection.

invalid_request

The request body failed basic schema validation before it was even sent to the orchestrator.

Verify the API request body matches the Create a new database connection

 request schema (required fields, types, and enum values).

network_error

A network-layer error occurred while contacting the database (for example, a DNS resolution failure).

Verify server_address is reachable from the gateway (host and port). Check routing, firewall, and security group rules between the gateway and the database.

If server_address is a hostname, also confirm it resolves correctly. If it's an IP, DNS doesn't apply.

orchestrator_timeout

An orchestrator picked up the job, but could not finish creating the integration before the timeout.

Check network latency and connectivity to the database instance, and ensure the instance was not overloaded at the time of the request. Retry the request.

orchestrator_unavailable

No orchestrator picked up the create-integration job within the allotted time.

Confirm a gateway is registered and connected: GET /teams/{team_name}/infrastructure-orchestrators?has_gateway=true and check that gateway_count is greater than 0 for the orchestrator referenced by infrastructure_orchestrator.id. Restart or redeploy the gateway if it is disconnected, then retry. See Okta Privileged Access gateways. 

read_only_error

The target database instance is a read-only instance. OPA requires write access to manage accounts and rotate passwords.

Point the connection at the primary (write-enabled) instance instead of a read only instance.

timeout

An unspecified timeout occurred with no more specific cause identified.

Retry the request. If it persists, check overall network health between the gateway and the database server, and contact Okta Support if the issue persists.

unknown_error

A generic, non-user-actionable server-side failure occurred (for example, a canceled operation or an unrecognized/internal-only orchestrator error code).

Retry after a short wait. If the error persists, contact Okta Support with the connection name and the approximate timestamp of the failed request.

unsupported_version

The database instance is running a version older than OPA supports. The message field states the minimum supported version for the database type and the version OPA detected.

Check the database server version against the supported versions. See Supported database types, versions, and deployment options.

wrong_credentials

Authentication to the database failed. The username or password for the management account is incorrect.

Verify the integration user username and password.