When creating a new policy rule (such as an IdP Routing Rule) via Okta Policy API or Management SDK, the request may fail with the following error.

504 Gateway Timeout

This typically occurs in environments with a high volume of existing rules when the new rule is being inserted at a high-priority position (for example, Priority 1).

• Okta Policy API
• Okta Management SDK
• Okta Identity Engine (OIE)

The latency is caused by rule re-indexing. When a new rule is inserted at a high-priority position (for example, Priority 1), the Okta backend must increment the priority and re-index all existing rules below it.

In orgs with a large rule set, this massive re-indexing operation can exceed the API's response timeout threshold. While the operation might eventually succeed in the background, the admin receives a 504 Gateway Timeout because the connection is severed before the re-indexing completes.

To resolve this, use the following strategies to reduce system overhead and ensure successful API responses.

1. Optimize the rule insertion.

Avoid inserting rules at Priority 1. Instead, append them to the end of the list to minimize the re-indexing of existing rules.

• • Option A: When using the Okta Policy API or any Okta Management SDK to create a new policy rule, simply remove the priority field from the request body. Okta will automatically default the new rule to the lowest priority.

  • Option B: Set the priority to a value significantly higher than the current rule count (for example, 999).

SDK Implementation Example (Node.js):

const newRule = {
  type: 'RESOURCE_ACCESS', // or 'IDP_DISCOVERY', etc.
  name: 'New Routing Rule',
  // priority: 1,  <-- avoid this in large rule sets
  priority: 999, // use a high number to append to the end, or omit entirely
  conditions: { /* ... */ },
  actions: { /* ... */ }
};

Direct API Call (Postman / cURL) Implementation Example:

When using the Policy API, ensure the priority field in the POST body is not set to 1. Leave the priority field out or use a high number to append closer to the end.

• Endpoint: POST /api/v1/policies/{policyId}/rules

2. Simplify and consolidate the rules.

If the business logic requires a rule to be at Priority 1, consider reducing the total rule count to improve overall management and evaluation performance:

• • Consolidate via Groups: Instead of individual rules for every scenario, use Okta Groups within a single rule's conditions to cover multiple user sets.

  • Utilize Policy Groups to logically separate rules, reducing the number of rules processed within a single container.