not_found error: fixing unresolved resource keys

HTTP status: 404

The Management API returns not_found when a request path names a resource it can’t resolve: the resource doesn’t exist, or the calling token isn’t allowed to see it.

Common causes

• A misspelled org, project, flag, environment, or segment key.
• A Service Token whose project allowlist excludes the target project.
• A resource that was deleted.

Why token scope shows up as not_found

A project outside a Service Token’s allowlist gets the same status and message as a project that doesn’t exist. This is deliberate. If the API answered forbidden instead, a token could confirm which project keys exist in an organization it was only partly granted. So when a key you’re sure is right still returns not_found, check the token’s allowlist before anything else.

Recovery hints in the response

Two optional fields help a client, script, or agent recover without a second guess.

• did_you_mean lists up to three existing keys within two character edits of the one you sent, closest first. It catches typos like a dropped or swapped letter. Only keys the calling token can see are suggested, and the field is left out when nothing is close.
• next_actions gives a follow-up request that lists the collection you were searching. A project miss points at the organization’s projects, and a flag or segment miss points at that project’s flags or segments. Environment misses don’t include it.

How to fix

Check the key/slug in the path. If a did_you_mean array is present, try one of its suggestions. If not, call the next_actions request to see the keys that do exist. Confirm the token’s project allowlist includes the project.

Example

{
  "error": "not_found",
  "message": "Flag not found",
  "docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
  "did_you_mean": ["new-checkout"],
  "next_actions": [
    {
      "method": "GET",
      "path": "/api/v1/orgs/{organizationId}/projects/{projectId}/flags"
    }
  ]
}