Oracle Fusion REST API 404 Not Found: Common Causes and Fixes

A 404 Not Found from an Oracle Fusion REST API is easy to misread as “the record doesn’t exist” when the actual cause is almost always the URL itself — a missing version segment, a resource name that changed modules ago, or a composite key that can’t be looked up by direct path. Cloud Customer Connect has multiple open threads on exactly this confusion, spanning HCM (/emps returning 404 after a resource rename, discussion 785528), SCM (ItemsV2 child-attribute lookups, discussion 804580), Projects (discussion 766095), and even a recent attachment-download case (discussion 940675). Oracle Support’s knowledge base has its own module-specific writeup too (Doc ID 2657952_1, HCM REST API payload 404s). None of these tie the causes together across modules, so this post does.

All examples use an anonymized pod (acme.fa.us2.oraclecloud.com) and placeholder identifiers.

First, rule out what 404 is not

Code	Means	Not covered here
400	Request is malformed or invalid	See the 400 Bad Request guide
401 / 403	Authentication or authorization failure	See the authentication guide
412	ETag mismatch on PATCH	See the ETag/If-Match guide
429	Rate limited	See the rate limits guide
500	Server-side failure after Oracle accepted the request	See the 500 Internal Server Error guide
404	The URL itself doesn’t resolve to a resource — not a validation or permission failure	This post

That distinction matters: a 404 means Oracle never got far enough to evaluate your payload or your role. Fix the URL first before assuming anything about the record or your access.

1. Missing or wrong version segment

Every Fusion REST path needs a version in it — 11.13.18.05, latest, or a specific numbered release. Drop it, misspell it, or reference a version that predates the resource, and Oracle returns 404 rather than a version-negotiation error. This is the single most common cause across the threads above: a URL that reads correctly to a human (.../resources/workers) but is missing the segment Oracle actually requires (.../resources/11.13.18.05/workers).

# 404 — no version segment
GET https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/workers

# Works
GET https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers

Check the resource’s page in the endpoint catalog for the earliest version it’s actually available under — latest isn’t a safe substitute if you’re on an older pod that hasn’t caught up.

2. A deprecated or renamed resource path

Discussion 785528 is a textbook case: /fscmRestApi/resources/latest/emps returns 404 on HCM 24B because emps was retired in favor of /workers and /userAccounts. The old path doesn’t redirect or error with anything more specific than a plain 404 — it just stops existing. The same pattern shows up whenever Oracle splits or renames a resource across releases; if a URL that worked last quarter now 404s with no other change on your side, check the resource’s current name in the catalog before assuming a permissions or environment problem.

3. Composite or alternate keys don’t resolve by direct path

Discussion 766095 and the wider “resource path segment doesn’t match a record” pattern usually trace back to this: some resources use a composite key (multiple identifier fields combined) or an alternate key, and putting the wrong form of the key directly in the URL path returns 404 even though the record exists. The documented workaround is to drop the ID from the path and filter with q instead:

# 404 — wrong key form in the path
GET .../fscmRestApi/resources/11.13.18.05/contracts/300000024471223

# Works — same record, looked up by q instead of path
GET .../fscmRestApi/resources/11.13.18.05/contracts?q=ContractId=300000024471223

This is also the safer default any time you’re not certain whether a resource’s primary key, alternate key, or a composite key is what the path segment expects — see the q parameter guide for syntax.

4. Child resource accessor name is wrong or unavailable

Discussion 804580 (ItemsV2 EFF values) and discussion 940675 (attachment FileContents via an automated caller) are both child-resource 404s: the parent record resolves fine, but the child accessor name in the path is wrong, was renamed, or isn’t exposed for that specific parent record’s configuration. Check the parent resource’s /describe output for its actual list of child resource names — don’t assume a child accessor visible in one context (a similar resource, an older API version, the UI) exists identically here.

5. Authentication failures that surface as 404 instead of 401

This one is counterintuitive and worth knowing about even though it’s less common with a direct REST client than with some middleware connectors: certain unauthenticated or improperly-authenticated requests to Fusion return 404 Not Found rather than 401 Unauthorized, because the request fails before Oracle’s routing layer confirms the resource even applies to an authenticated caller. If a URL you’re confident is correct 404s with no other explanation, double-check that your credentials are actually being sent on the request — some HTTP clients only send Basic Auth headers after a first challenge-response round trip, and if that handshake doesn’t complete, the symptom you see is 404, not 401.

Diagnostic checklist

1. Confirm the version segment is present and valid for the resource you’re calling — check the endpoint catalog for the earliest supported version.
2. Confirm the resource name itself hasn’t been renamed or deprecated (the /emps → /workers pattern repeats across modules).
3. If you’re putting an ID directly in the path, try the q-filter form instead — composite and alternate keys frequently fail to resolve by path.
4. For child resources, check the parent’s /describe output for the real accessor name rather than assuming it matches a similar resource.
5. Confirm your auth headers are actually present on the request itself, not just configured in the client — a failed pre-auth handshake can present as 404.

Where OPAL fits

Because a 404 is almost always a URL problem, not a data or permissions problem, the fastest fix is confirming the exact path — version, resource name, and child accessors — against the real catalog rather than guessing from an older integration or a similar resource. OPAL bundles the full Oracle Fusion Cloud spec offline and lets you browse to the exact resource, see its current name and supported versions, and expand its real child resources before you build the call — so a renamed or version-mismatched path gets caught before you ever send the request.

---

This post is part of our complete Oracle Fusion API guide — base URLs, authentication, q filters, finders, and common errors in one place.