Troubleshooting

Every decide error answers { "error": { "code", "message" } }. A name that got no decision is not an error: it comes back in unknown. Refusals on the /edgekit/ mount itself, such as CORS errors or a forwarder dropping a header, are covered in First-party mount troubleshooting.

What each decide refusal means

Status	`code`	Message	Cause
`400`	`bad_request`	`Missing site id.`	No `x-edgekit-site-id` header. On `/decide/forward`, no header and no `site` parameter
`401`	`unauthorized`	`Missing API key.`	`POST /v1/decide` without a key. From a page, the request reached `/v1/decide` instead of `/edgekit/v1/decide`
`401`	`unauthorized`	`Invalid or missing API key.`	The key is unknown, revoked or expired
`403`	`forbidden`	`This key is not pinned to the selected site.`	The key belongs to another site
`403`	`forbidden`	`This origin is not allowed for the selected site.`	The page’s origin is not in the site’s allowed origins
`403`	`forbidden`	`This route reads identity from the access cookie, never from the body.`	A `userId` sent to `/edgekit/v1/decide` or `/decide/forward`
`403`	`forbidden`	`The content descriptor did not verify.`	The `content` signature is wrong, or its payload is not a JSON object
`404`	`not_found`	`Unknown site.`	The site is not active, or not in your newest deployment
`404`	`not_found`	`"<name>" is not a published journey feature on this site.`	`/decide/forward` was given a feature that is not a deployed journey feature on the site
`413`	`payload_too_large`	`Request body too large.`	The body is over 64 KB
`422`	`unprocessable_entity`	`Request validation failed.`	The body does not match: no `features`, more than 32, an empty name, or a field of the wrong type
`422`	`unprocessable_entity`	`This site cannot take an asserted userId.`	A `userId` at a site where users sign in only through your own identity provider
`429`	`too_many_requests`	`Too many decide requests.`	Over the rate limit. Wait the `Retry-After` seconds. See Limits
`500`	`internal_error`	`This feature has no resolvable redirect.`	`/decide/forward`: neither the outcome’s URL nor its fallback URL resolved to one of the site’s redirect origins
`503`	`service_unavailable`	`This tenant has no deployed configuration.`	Your organization has no deployment yet
`503`	`service_unavailable`	`This tenant cannot verify content facts.`	The request carries `content`, and EdgeKit has not set up signed content facts for your organization
`503`	`service_unavailable`	`This tenant has no meter store configured.`	Decide is not set up for your organization. Contact EdgeKit

The browser client and the server client answer unavailable for every feature on a timeout and on any refusal other than a 400, 401, 403 or 404, such as a 413, 422, 429 or 5xx. On those four, both throw EdgeKitConfigError, since they are setup mistakes.

A feature I authored comes back in `unknown`

Decide answers a name in unknown when it is not a feature in your newest deployment or does not run on the site. Check, in order:

It is deployed. A saved change reaches requests only after a deploy in Delivery › Deployments › Versions.
It is in the deployment. A feature left out of the next deploy is marked not in next deploy in the Features list. A feature created in the console starts that way, and the feature screens have no control that includes it.
It runs on this site. A feature with sites picked answers only on those sites.
The name matches. Names are lowercase. A renamed feature answers only to its new name.

Every request gets the error outcome

The decision’s reason is error when the canvas could not read something a rule needed and no rule won. Common causes:

Content item facts. A rule that tests an item.* fact cannot be read on a decide request, which carries no content item.
Trait completeness from a page. db_user_traits.complete cannot be read on /edgekit/v1/decide. Decide it from your server, where it can.
A computed field with no value. An outcome whose computed field’s fact cannot be read makes the canvas return its error outcome.

An entry that cannot be read is different: the canvas is not entered, and the next canvas is tried. Use Preview in the builder to see where a caller lands. See Try it with Preview.

`outcome` is `null`, or `(unresolved outcome)`

null: the slot that answered returns no outcome. Fill every then return, everyone else, on error and Fallback slot.
(unresolved outcome), with type deny and reason error: the slot points at an outcome that does not exist. Stage refuses this, so redeploy from a draft where every slot points at a named outcome.

A user with access sees the outcome for no access

The response says staleIdentity. The request had a sign-in session but no usable access cookie, so it was decided with no grants. The access cookie stops being accepted 15 minutes after the last decide that renewed it, and an hour after the user’s grants were last read into it. The browser client refreshes it once, in the background, and the next decide is right. To avoid the one wrong answer, read the sign-in session when the page loads, before you decide.
The canvas tests user.state alone. paid means the user holds a live grant for any product in your organization. Test grants.product_ids for the product this page needs too.
The grant is new. A grant bought or changed elsewhere reaches page decisions the next time the page reads the sign-in session, and at most an hour later.
The page calls your tenant host directly. Without /edgekit/ on your own domain, the sign-in cookie may not reach decide, and the request is anonymous. See Call the tenant host directly.
The user holds a very large number of grants. When the user’s grants and sites are too many to fit in the access cookie, no access cookie is written, and page decisions treat the user as an anonymous device. Decide from your server for that user.

Anonymous users run out of free reads at once

Every request without a device cookie shares one count, so a device meter fills up for all of them together. The device cookie is set by EdgeKit Analytics when your site’s tracker sends events. Run the tracker on your pages before they decide. See EdgeKit Analytics.

A meter never moves

The rule that won has no +1. Only the winning rule counts, and only with +1 if this rule wins.
The user holds a grant. By default, a user with any live grant counts on no meter except a gift link’s.
The meter is a user meter and the request is anonymous. Anonymous reads are never counted on it.
The feature is operational. A flag counts on no meter.
The meter is not deployed. A new meter starts left out of the next deploy.
The meter is a seen-set and the request has no key. A read whose request carries no value for the meter’s key fact is never counted.

`/decide/forward` does not redirect

404, "<name>" is not a published journey feature on this site.: the feature is not a deployed journey feature on this site.
500, This feature has no resolvable redirect.: the outcome’s URL used a field with no value, or its origin is not in the site’s redirect origins, and so did its fallback URL.
200 with the text edgekit.cloud alive: the request reached a path your tenant host does not serve. See First-party mount troubleshooting.

Creating a gift link is refused

Status	Message	Cause
`401`	`Sign in to create a gift link.`	The browser route needs a signed-in user
`403`	`Only a keyed caller may shorten a gift link.`	`expiresInDays` on the browser route
`404`	`Gift links are not configured for this tenant.`	Your organization’s create feature or key fact is not set
`404`	`"<name>" is not a published feature on this site.`	The create feature is not deployed, or does not run on this site
`422`	`This page carries no <key fact>.`	The page’s facts have no value for the key fact
`422`	`This site cannot take an asserted userId.`	A server sent `userId` at an `external_only` site
`503`	`This tenant cannot sign gift links.`	Gift links are not set up for your organization. Contact EdgeKit

A refusal by the create feature itself is not an error: it is 200 with status denied. See Gift links.

Stage refuses my feature

The deployments screen lists each failure and where it was found. The common ones:

No canvas. A feature needs at least one.
An empty entry. Use Everyone to capture everybody.
An entry that reads a meter or an experiment arm, directly or through a segment.
An error outcome that allows, in a feature that has allow or deny outcomes.
An outcome that is not deployed. A slot points at an outcome that is deleted or left out of the next deploy.
A meter that is not deployed, or does not run on every site the feature runs on.
Two outcomes with one id and different fields in one feature.
A count from a flag. An operational feature with +1 if this rule wins, an offer token, or a fact it may not read.
A crawler fact on a site with no crawler verdict.