Why an API returns 404 Not Found, and how to fix it
An API returns 404 when no route matches your path or method, or when the id doesn't exist for your credentials. How to tell them apart and fix each.
An API returns 404 Not Found for one of two reasons: no route matches the request, because the path, version, or HTTP method is wrong, or the route exists but the resource you named doesn't, at least not for the credentials you sent. Read the response body before you change anything, because the fixes differ: a wrong address needs a new URL, and a missing resource needs a different id or key.
The HTTP definitions are quoted from RFC 9110, read 2026-09-28. The Sume API is the worked example: its 404 bodies are read from its current code, alongside its Errors and spend and Errors and rate limits docs.
What does 404 Not Found mean on an API?
RFC 9110 says a 404 means the server did not find a current representation for the target resource, or is not willing to disclose that one exists. It doesn't say whether the condition is temporary or permanent.
A wrong method has its own status in the spec: 405 Method Not Allowed, whose response must list the supported methods in an Allow header. Not every server sends it. In current code the Sume API doesn't: a request with the wrong method gets the same 404 as a path that doesn't exist.
How do I tell a wrong URL from a missing resource?
Read the body. On the Sume API, each case answers differently in current code:
| What went wrong | What Sume returns | Fix |
|---|---|---|
A path outside /v1, such as a missing version prefix | 404 with {"message":"Route not found"} | Add the /v1 prefix. |
An unknown path under /v1, or the wrong method | 404 not_found, API route was not found. | Check the path and method in the API reference. |
| A Format run read under the Format's own path | 404 format_run_wrong_path, with the right route in details.did_you_mean | Read runs at GET /v1/format-runs/{run_id}. |
| An unknown job id, or one created in another workspace or with another member's key | 404 not_found, API job was not found. | Check the id and the key that created it. |
| An unknown or archived Format, or a team handle you can't see | 404 format_not_found | Check the address and the key. |
Why does an API return 404 for an id I know exists?
Because the id isn't visible to the credentials you sent. RFC 9110 lets a server that wants to hide a forbidden resource answer 404 instead of 403.
On Sume, jobs are looked up inside the key's own workspace and owner in current code, and the docs define 404 not_found as a resource that does not exist in the current workspace. On the Formats API, a run belonging to another owner reads the same as one that does not exist. Scope problems aren't hidden this way: on the Formats API, a key missing a scope gets 403 insufficient_scope, never a 404. List and recover video jobs shows how to find the ids your key can see, and 401 vs 403 vs 404 covers the other two codes.
Why does my POST return 404 when the URL looks right?
Check the method and the exact path. In current code a path the API doesn't define gets API route was not found.: POST /v1/videos/generations answers 404, while the documented route is POST /v1/videos. A known path called with the wrong method gets the same answer.
The key is checked first. In current code the key check runs on every /v1 path before the not-found answer, so a bad key gets 401 even on a wrong path. API route was not found. therefore means the key passed and the address is what's wrong.
Should I retry a 404?
Not as is. A 404 carries no hint about whether or when it might clear, so fix the path, the method, the id, or the key first. In current code Sume marks a 404 retryable: false with next_action: fix_input. Retryable HTTP status codes lists the errors that do deserve another try.
Sources
Related posts
More in Developers
- API vs SDK: what's the difference, and do you need one?
An API is the contract: routes, fields and errors. An SDK is a library in one language that calls that API for you. What an SDK adds, and when to skip it.
- Arcads API: how it works, from credentials to video
Arcads has a public API: Basic auth with a client ID and secret, then a brand, a folder and a script, one generate call, and a poll for the video URL.
- Asynchronous request-reply pattern: how it works
In the asynchronous request-reply pattern, the server accepts work with a 202 and a status URL, and the client polls or takes a callback until it's done.
- asyncio Semaphore: limit concurrent API jobs in Python
An asyncio Semaphore caps how many coroutines run a block at once. For paid API jobs, hold it from submit to the final status and size it to your limit.
Written by Sume