Skip to main content

Global settings

Global settings are the parts of DIAL Core's dynamic configuration that apply to the whole deployment rather than to one entity: interceptors that run for every deployment, extra error codes that trigger failover, the calendar that limit windows follow, and how spending limits are enforced. This reference is for platform engineers who set deployment-wide policy; it assumes you know how DIAL Core is configured.

Where global settings are defined​

SourceLocation
Config fileThe top-level keys globalInterceptors, retriableErrorCodes, rateLimitSchedule, and spendingLimits
Configuration APIOne entity, /v1/settings/platform/global

When the settings/platform/global blob exists, Core takes all four fields from it instead of from the files. A field missing from the blob reads as empty: globalInterceptors and retriableErrorCodes as [], rateLimitSchedule with time zone UTC, and spendingLimits with mode off and cost object ORG. Deleting the blob restores the file values. A PUT drops unknown fields and answers 400 on an invalid rateLimitSchedule or spendingLimits.

Global interceptors​

globalInterceptors lists interceptors that run for every deployment. They see the original request first and the final response last.

{ "globalInterceptors": ["audit-logger", "prompt-injection-check"] }

Each name must be a registered interceptor.

Retriable error codes​

retriableErrorCodes lists extra HTTP status codes that make Core fail over to another upstream when a provider has an outage. The list extends the built-in codes 429, 502, 503, and 504; it does not replace them. See Load balancing and upstreams.

{ "retriableErrorCodes": [500, 408] }

Rate limit schedule​

rateLimitSchedule anchors the fixed calendar windows of the day, week, month, and requestDay limits on roles. It is one setting for the whole deployment, with no per-role or per-user override.

FieldDefaultDescription
timezoneUTCAn IANA time zone ID, such as Europe/Warsaw. A fixed UTC offset is not accepted, because it cannot follow daylight saving time.
weekStartDayMonThe first day of the week window: Mon, Tue, Wed, Thu, Fri, Sat, or Sun.
resetTime00:00The local time, HH:mm, at which the windows reset.
{
  "rateLimitSchedule": {
    "timezone": "Europe/Warsaw",
    "weekStartDay": "Mon",
    "resetTime": "09:00"
  }
}

Spending limits​

spendingLimits switches spending control between the role costLimit and budgets.

FieldDefaultDescription
modeoffoff, shadow, or enforce.
defaultCostObjectORGThe cost object charged for a call that carries no project.
ModeCallers who sign in through an identity providerCallers with API keys
offThe role costLimit applies.The role costLimit applies.
shadowBudgets are checked, metered, and charged, but never reject a call; the role costLimit still decides. A call that enforce would reject is logged at INFO with the reason, user, cost object, and model.The role costLimit applies.
enforceOnly budgets apply; a call answers 429 when no budget can pay for it. The role costLimit is ignored.The role costLimit applies.

In shadow and enforce, when defaultCostObject has no unexpired cost budget, Core logs a warning on each configuration rebuild and sets the gauge dial_budget_personal_missing to 1.

Budgets are stored as policies and policy assignments in the platform bucket; the Core documentation does not describe their fields yet. Their spend counters are cleaned up by the budget counter sweep.

Other top-level keys​

These keys sit at the top level of a config file but are not part of the global settings entity:

KeyDefaultDescription
defaultLocaleenThe BCP-47 locale of plain-string displayName, description, and intro values, and the fallback locale for localized fields across the configuration.
orgUnitRoles—Roles that can be assigned at an org unit, replacing or adding to the built-in admin, editor, viewer, and member. Org units are a preview feature, off unless orgUnits.enabled is true.

Example​

{
  "globalInterceptors": ["audit-logger"],
  "retriableErrorCodes": [500],
  "rateLimitSchedule": { "timezone": "UTC", "weekStartDay": "Mon", "resetTime": "00:00" },
  "spendingLimits": { "mode": "shadow", "defaultCostObject": "ORG" }
}

The same values through the Configuration API:

curl -X PUT "https://<DIAL_CORE_HOST>/v1/settings/platform/global" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"globalInterceptors": ["audit-logger"], "retriableErrorCodes": [500], "spendingLimits": {"mode": "shadow"}}'

Further reading​