Network API error reference

This page documents common error responses from the Network API (Neutron), organized by resource type. Each error includes the typical cause and a resolution path. Use this reference when network operations return unexpected status codes or when resources enter unexpected states.

Common HTTP status codes#

Error response envelopes#

The Network API returns two different error envelopes depending on the status code.

400, 403, 404, and 409 responses use the NeutronError envelope:

{
  "NeutronError": {
    "type": "SecurityGroupRuleExists",
    "message": "Security group rule already exists. Rule id is 6349a8bf-c74c-42c8-935f-fc56eff67bd8.",
    "detail": ""
  }
}

401 responses use a different envelope with code, title, and message keys:

{
  "error": {
    "code": 401,
    "title": "Unauthorized",
    "message": "The request you have made requires authentication."
  }
}

An invalid, expired, or missing X-Auth-Token header returns 401 with the error envelope. Quota and authorization failures return 403 with the NeutronError envelope. Read the top-level key (error or NeutronError) before parsing the fields.

Port-related errors#

Port in use (409 Conflict)#

Symptom: Attempting to delete a port returns "Port is still in use."

Cause: The port is attached to an instance, router interface, or floating IP.

Resolution:

1. Check what owns the port:

openstack port show YOUR_PORT -c device_owner -c device_id

1. If device_owner is compute:nova: the port is attached to an instance. Detach or delete the instance first.

2. If device_owner is network:router_interface: remove the router interface:

openstack router remove subnet YOUR_ROUTER YOUR_SUBNET

1. If device_owner is network:floatingip: deleting the port succeeds (HTTP 204). Neutron auto-disassociates the floating IP, which survives in DOWN state and can be re-associated. You do not need to disassociate the floating IP first.

Port binding failure#

Symptom: Instance creation fails with "PortBindingFailed" in the server fault.

Cause: The Networking service cannot bind the port to a compute host. This typically indicates the selected network is not available on the compute host where the instance was scheduled.

Resolution:

1. Verify the network exists and is accessible to your project:

openstack network list
openstack network show YOUR_NETWORK -c provider:network_type

1. Recreate the instance on a different network, or file a support ticket if the network should be available.

Port security and allowed address pairs#

Symptom: Traffic from containers or nested VMs is dropped even though security group rules allow it.

Cause: Port security enforces anti-spoofing rules. Traffic with a source IP that does not match the port's fixed IP or allowed address pairs is dropped.

Resolution:

Add the additional IP ranges as allowed address pairs:

openstack port set --allowed-address ip-address=CONTAINER_SUBNET YOUR_PORT

Or disable port security entirely (less secure):

openstack port set --no-security-group --disable-port-security YOUR_PORT

Router-related errors#

Router interface conflict (409 Conflict)#

Symptom: Adding a subnet to a router fails with a conflict error.

Cause: The subnet is already attached to another router, or the subnet's gateway IP conflicts with an existing interface.

Resolution:

1. Check if the subnet is already attached to a router:

openstack router list
openstack router show EACH_ROUTER -c interfaces_info

1. Remove the subnet from the other router before adding it to the new one:

openstack router remove subnet OTHER_ROUTER YOUR_SUBNET
openstack router add subnet YOUR_ROUTER YOUR_SUBNET

External gateway conflict#

Symptom: Setting the external gateway on a router fails.

Cause: The external network does not exist, is not marked as external, or your project does not have access to it.

Resolution:

1. List available external networks:

openstack network list --external

1. Set the gateway using a valid external network:

openstack router set --external-gateway EXTERNAL_NETWORK YOUR_ROUTER

Router deletion blocked (409 Conflict)#

Symptom: Deleting a router fails because it has active interfaces or a gateway.

Resolution:

1. Remove all interfaces:

openstack router remove subnet YOUR_ROUTER SUBNET_A
openstack router remove subnet YOUR_ROUTER SUBNET_B

1. Clear the external gateway:

openstack router unset --external-gateway YOUR_ROUTER

1. Delete the router:

openstack router delete YOUR_ROUTER

Floating IP errors#

Floating IP association failure#

Symptom: Associating a floating IP to an instance fails with a 400 or 404 error.

Cause: The target port does not exist, the floating IP is already associated, or the port is not on a network connected to the router with the external gateway.

Resolution:

1. Verify the floating IP is unassociated:

openstack floating ip show YOUR_FLOATING_IP -c port_id

If port_id is not null, disassociate it first:

openstack floating ip unset --port YOUR_FLOATING_IP

1. Verify the instance's network is connected to a router with an external gateway:

openstack port list --server YOUR_INSTANCE
openstack router list

Floating IP quota exceeded (403 Forbidden)#

Symptom: Allocating a new floating IP returns "Quota exceeded for resources: floatingip."

Resolution:

1. Release unused floating IPs:

openstack floating ip list
openstack floating ip delete UNUSED_FLOATING_IP

1. If all floating IPs are in use, request a quota increase through the support portal.

Security group errors#

Duplicate rule (409 Conflict)#

Symptom: Creating a security group rule fails with "Security group rule already exists."

Cause: An identical rule (same direction, protocol, port range, remote) already exists in the security group.

Resolution:

List existing rules to confirm:

openstack security group rule list YOUR_SECURITY_GROUP

No action needed if the existing rule matches your intent.

Security group in use (409 Conflict)#

Symptom: Deleting a security group fails because it is assigned to one or more ports.

Resolution:

1. Find which ports use the security group:

openstack port list --security-group YOUR_SECURITY_GROUP

1. Reassign those ports to a different security group:

openstack port set --security-group REPLACEMENT_SECURITY_GROUP YOUR_PORT

1. Delete the security group:

openstack security group delete YOUR_SECURITY_GROUP

Rule limit exceeded#

Symptom: Creating a security group rule fails with a quota error.

Cause: Each project has a limit on the total number of security group rules.

Resolution: Delete unused rules or security groups to free capacity, or request a quota increase.

When to escalate#

Escalate to support when:

• A port remains in DOWN state despite correct configuration and the instance is running
• A floating IP is associated and security groups are correct, but external traffic still cannot reach the instance
• Router interface operations fail with errors that do not match any documented conflict pattern
• A 409 Conflict persists after resolving all visible dependencies (port ownership, subnet attachments)

Escalation-ready evidence checklist#

When a Network API error is not self-resolvable, collect this evidence:

See also#

• Network API reference
• Error response format: JSON error structure, request correlation
• API rate limits: quotas vs. rate limits, /limits endpoint, 429 handling
• Retry and resilience patterns: backoff, jitter, and which errors to retry
• Instance connectivity troubleshooting
• How to create security group rules
• How to allocate floating IPs