Errors and retries

Every error from Director has the same JSON body. Decide what to do from the status code and, where present, the code field.

The error body

{"detail": "invalid or missing API key"}

• detail is a sentence for people. Show it or log it. Do not match on its text, because wording can change.
• code is a stable identifier for programs. It appears on the errors that have one, listed below.
• field, reason, and variable appear on some errors and add detail for programs.
• Error bodies are JSON whatever Content-Type or Accept you sent.

Status codes

A call that is refused before the model runs (400, 401, 404, 406, 413, 415, 422, 429, and the 503s for an unreachable account service or billing) costs nothing.

Retry rules that matter

• Never retry a 4xx unchanged. The request or the account has to change first.
• Never retry a 429 automatically. Space out your calls, or fix the cause, then try again from a human decision or a scheduled job.
• Never automatically retry a call that timed out and may have been billed. A timeout on your side does not mean Director did nothing. Check GET /v2/usage/me before you repeat it.
• Back off on 502 and 503, for example after 1, 5, and 15 seconds, and give up after a few tries. Meanwhile your game runs its scripted behavior.

Each status in detail

400 Bad Request

The model selection is wrong. The body has "code": "invalid_selection" and field, which is provider or model. See Models and usage.

Or max_tokens is out of range, not a whole number, or repeated: "code": "invalid_max_tokens", "field": "max_tokens", with the accepted min and max. A request with both problems gets the selection error. Nothing runs and nothing is charged.

Or rationale is something other than true or false, empty, or repeated: "code": "invalid_rationale", "field": "rationale". A request that also has a selection or max_tokens problem gets that error first. Nothing runs and nothing is charged.

401 Unauthorized

The body is always the same, so a response tells you nothing about which keys exist:

{"detail": "invalid or missing API key"}

Causes: no Authorization header, a scheme other than Bearer, a mistyped or truncated key, a revoked key, or a key from another service. Check that the header is exactly Authorization: Bearer epd_... with one space and no quotes. A revoked key stops working within 60 seconds. If the key is lost, create a new one. Retrying the same key never helps.

403 Forbidden

The credential is valid, but the account's plan does not include the hosted Director. It needs Pro or higher; Free and Starter accounts are refused on every authenticated endpoint. Studio keys and a local Director are not affected. Upgrade the plan, then retry.

{"detail": "'engine' is not included in the Free plan.", "code": "feature_not_in_plan", "feature": "engine", "hint": "Available on Pro and above.", "retryable": false}

Or the key is valid, but a module that the endpoint needs is not enabled for the account. Plots endpoints need the Plots module, Memory endpoints need the Memory module, and POST /v2/events needs at least one of the two. POST /v2/decide, the policy, and DELETE /v2/worlds/{world_instance_id} do not need a module. Plots and Memory are off by default. Switch them on under Modules at https://architect.eposyne.com/profile?section=director-keys. A switch reaches API keys within a minute and sign-in tokens within an hour. Do not retry before that.

{"detail": "module 'plots' is not enabled for this tenant"}

404 Not Found

Every route under the earlier prefix /v1 answers this body, whatever the method:

{"detail": "director/v1 routes are retired in this runtime; use /v2", "code": "contract_retired"}

Change the prefix to /v2 and send the JSON request of The decide request. For the other 404s the body is {"detail": "..."}. On DELETE /v2/plots/library/{arc_id} the library holds no such arc. On GET /v2/memory/runtime/npcs/{npc_id} the timeline was never sent, or Memory holds nothing for that character on it. The older Plots and Memory routes (templates, arcs, trigger, evaluate, entities, runs, context, consolidate, debug) are not available to accounts and answer {"detail": "Not Found"}, as an unknown route does. Do not retry unchanged.

409 Conflict

A decision that names a stream position (world, timeline, after_seq) came before Director held every event up to that position. The body lists what Director holds and what is missing. Resend the missing events, then repeat the decision. Never repeat the same request unchanged in a loop. Plain decisions without a stream position never get this error. On POST /v2/events, a 409 means a timeline already exists with a different parent, or a limit on worlds or timelines was hit. Never retry that one unchanged. Fix the timeline, or delete a world. The codes are in Errors of events, policy, Plots, and Memory.

406 Not Acceptable

{"detail": "Not acceptable: v2 routes answer application/json", "code": "not_acceptable"}

The Accept header is present and none of its entries admits application/json (*/* and application/* do). Director answers JSON only. Leave the header out or fix it. No model ran.

413 Payload Too Large

{"detail": "Request body exceeds 262144 bytes", "code": "body_too_large"}

A body over 262,144 bytes is refused with "code": "body_too_large" on every /v2 route that takes one. Director also estimates the prompt before it calls a model: a prompt over 30,000 input tokens is refused with "code": "prompt_too_large". Send fewer variables and a shorter ask. See Writing requests.

415 Unsupported Media Type

{"detail": "Unsupported media type: v2 routes take application/json", "code": "unsupported_media_type"}

The body came with a Content-Type that is not application/json, or with none, or with a charset other than UTF-8. An XML media type is refused like any other; Director never reads the body to guess a format. Fix the header. No model ran.

422 Unprocessable Entity

The body cannot be processed. The code says why:

A 422 without one of these codes is a partial stream position (one or two of the three parameters), a player_id parameter without a stream position, or an empty or repeated one. On the module endpoints it also means an event batch, a policy, or an arc that does not match its format, or a gap or size limit, see below. Fix the request.

429 Too Many Requests

Three different causes share this status. The detail says which one:

• Rate limit. More than 60 requests a minute for the account. All your keys share this limit.
• Credits refused. The body has "code": "credits_refused". Your balance is under EUR 1.00, or what is left after the reservations of calls in flight does not cover this call's reservation, or usage credits are off, or this month's credits spend has reached the monthly limit you set. The detail tells you which. Add credits or change the setting on the credits page.
• Monthly limit. A credits refusal with "reason": "monthly_limit_reached". The decision that crosses the limit completes; every later one that month is refused until the next UTC month, or until you raise the limit. resets_at in GET /v2/usage/me gives the moment.

{"detail": "Your usage credits balance is €0.99, under the €1.00 ...", "code": "credits_refused", "reason": "balance_under_floor"}

The reason is balance_under_floor, insufficient_for_hold, credits_off, or monthly_limit_reached. See Billing and limits for how a call reserves its cost.

Two more 429s have rate limits of their own: event_rate_exceeded on POST /v2/events and library_rate_exceeded on library writes. They carry a Retry-After header in seconds and are safe to retry after it. See below.

Show the detail text to the developer or the operator. Do not retry a credits refusal automatically.

502 Bad Gateway

The model backend could not produce an answer: a timeout after 30 seconds, a connection failure, or an unusable reply. A body with "code": "accounting_unavailable" means the provider did not report what the call cost; it is charged its reserved amount. A 502 or 500 after the model has answered is still charged what the call cost; a 502 because the provider failed before answering is not charged. In every 502 case your game should use its scripted behavior. If you retry, do it with backoff, and not after a timeout that may have been billed (see above).

503 Service Unavailable

• "code": "account_service_unavailable": Director could not reach the Eposyne account service, so it could not check your key or your credits. No decision was made and nothing was charged. A key that Director checked in the last minute keeps working until that check expires. A key it has not seen recently gets this 503. Retry with backoff.
• "code": "billing_unavailable": Director could not record the call for billing, so it ran nothing and charged nothing. Retry with backoff.
• "code": "model_unavailable": you chose no model and no default is available. Choose a pair from GET /v2/models.
• No code: the decision pipeline is not available on the deployment. Retry later with backoff.

Errors of events, policy, Plots, and Memory

These errors have a code. Match on the code, not on the detail text. A request that one of them refuses stores nothing.

An arc the library refuses for another reason is a 422 without a code. Its detail starts with arc bundle rejected: and lists every reason. See Plots.

Not errors: deferred and refused judgements

A successful POST /v2/events answers 200 and can carry two extra members. They report model calls of Plots and Memory, not failures of the request.

• "deferred": {"count": 70}: events held and acknowledged, but not processed yet, because one request runs at most 50 judgements. They are processed by the next delivery or by a decision with a stream position.
• "refused_judgements": {"count": 2, "reason": "balance_under_floor"}: judgements skipped because your credits could not pay for them. The events are processed as if nothing happened. The reasons are the credits reasons above, plus account_service_unavailable, billing_unavailable, prompt_too_large, and model_unavailable.

See Events.

Parse defensively

Within /v2 we may add endpoints, optional parameters, response members, headers, and new detail texts. We do not change the meaning of a status code or a code. Ignore members and headers you do not recognize.