401, 404, 405: Why Your ApyHub API Calls Fail and How to Fix Them

01Introduction

I'm seeing a lot of failed API calls these days. Most failed API calls are not API bugs. They are a missing header, a mistyped path, or the wrong HTTP method. Once you know how an ApyHub URL is built, these three errors take seconds to diagnose.

The examples below use the Decode and Validate VIN API (you can find my other APIs on my provider page if you're interested), but the rules apply to every service in the ApyHub catalog.

This guide covers the three most common API error codes on ApyHub, 401 Unauthorized, 404 Not Found and 405 Method Not Allowed: what each one means, how to fix it, and when not to retry.

02Anatomy of an ApyHub request

Every REST call follows the same pattern:

METHOD https://api.<region>.apyhub.com/<provider>/<service-slug>/<endpoint-path>

A real example:

curl -i "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decode?vin=1HGCM82633A004352" \
  -H "apy-token: $APY_TOKEN"

The best habit: copy the full URL and method from the service page. Do not rebuild them from a title or an old example. Titles and slugs do not always match, and every service page is available as Markdown if you append .md to its URL, for example decode-and-validate-vin-api.md.

03401 Unauthorized: the key is missing, misplaced, or from another region

A 401 means ApyHub did not recognise your credentials. The gateway answers with {"error":"missing api key"} when no key arrives, and {"error":"invalid api key"} when the key is wrong or sent the wrong way. The request never reached the service, so changing parameters will not help.

Common causes:

• Missing header: curl without -H "apy-token: $APY_TOKEN" is a valid but unauthenticated request.
• Wrong header name or value: REST endpoints documented on service pages use apy-token: <raw-key>. The MCP endpoint uses Authorization: Bearer; the two are not interchangeable, and the REST value must not be prefixed with Bearer.
• Token in the wrong place: A token in the query string or JSON body is not the documented REST method.
• Empty or malformed variable: $APY_TOKEN expands to nothing if it was never exported. A trailing newline or a copied space also causes a 401.
• Wrong region: The default host is https://api.eu.apyhub.com. A US workspace calls https://api.us.apyhub.com.

Wrong:

curl "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decode?vin=1HGCM82633A004352" \
  -H "Authorization: Bearer $APY_TOKEN"

Right:

curl "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decode?vin=1HGCM82633A004352" \
  -H "apy-token: $APY_TOKEN"

If the playground works but your code does not, the difference is almost always the header, the host, or the environment variable.

04404 Not Found: the URL does not match a published route

A 404 usually means the gateway could not match your URL to an endpoint. Check the four URL parts in order:

• Provider slug: "API Forge" maps to corsair96; the display name will not work in the path.
• Service slug: "Decode and Validate VIN API" maps to decode-and-validate-vin-api. A guessed slug like vin-decoder-api will not resolve.
• Endpoint path: /vin/decode is not /vin/decoder or /decode. Paths are case-sensitive, so copy the route exactly.
• Region host: api.eu.apyhub.com and api.us.apyhub.com are different hosts.

Also replace path parameters instead of sending them literally: if the docs show /status/{id}, call /status/inv_123.

# Missing provider slug
https://api.eu.apyhub.com/decode-and-validate-vin-api/vin/decode?vin=...

# Wrong service slug
https://api.eu.apyhub.com/corsair96/vin-decoder-api/vin/decode?vin=...

# Wrong endpoint path
https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decoder?vin=...

Gateway 404 vs. application 404

Not every 404 means your URL is wrong:

• Gateway 404: no route matches. ApyHub returns a generic {"error":"not found"}.
• Application 404: the route matched and the resource was not found. The service returns a specific code, for example {"error":"vin_not_found","message":"..."}.

If the error names the missing resource, the route is correct. Change the input, not the URL.

05405 Method Not Allowed: right URL, wrong verb

A 405 means the path exists, but it does not accept the method you used. The gateway answers with {"error":"method not allowed"}. Methods are part of the contract, not a detail.

This returns 405:

# GET on a POST-only route
curl -X GET "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/batch"

This is correct:

curl -X POST "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/batch" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vins":["1HGCM82633A004352","1FTFW1ET9DFC10312"]}'

Two related mistakes: sending a JSON body to a GET endpoint, and omitting Content-Type: application/json on a POST. Some gateways return 404 instead of 405 when the method does not match, so check the verb first if the path looks correct.

06The 60-second checklist

• Method matches the documentation (GET vs POST).
• Host matches your workspace region (eu or us).
• Provider slug is in the URL.
• Service slug is the published slug, not the display title.
• Endpoint path is exact, with path parameters replaced.
• Auth header is apy-token, with a non-empty key.
• Content type is set for POST and multipart requests.
• URLs are quoted in the shell, so ? and & are not interpreted.

Then read the response body, not just the status code:

curl -i "https://api.eu.apyhub.com/corsair96/get-blockchain-gas-prices-transaction-fee/crypto/gas?chain=ethereum" \
  -H "apy-token: $APY_TOKEN"

-i shows the status, headers, and body. That is often enough to see whether you hit the gateway or the service. (This example calls my Blockchain Gas Prices API.)

API error codes at a glance

Do not retry 401, 404, or 405: the same request will fail the same way. Retrying only makes logs noisier.

07Skip URL building with ApyHub MCP

If an AI agent makes the call, it can skip most of this. Through ApyHub MCP, an agent in Claude, ChatGPT, Cursor or any MCP client picks a service and endpoint from the catalog, and ApyHub fills in the route, the method and the authentication. The agent never assembles a URL by hand, so a mistyped slug or a wrong verb is much less likely.

Connect ApyHub MCP to your agent →

08Recap

• 401 means "I don't know who you are." Fix the apy-token header and use the right region host.
• 404 means "I don't know where you're going." Copy the provider, service, and endpoint path exactly.
• 405 means "I know where you're going, but not that way." Use the documented HTTP method.

ApyHub uses the same request shape across the catalog, so learning this pattern once pays off on every service. Start from the service page, copy the full URL and method, send your key in apy-token, and read the error body when something fails. Most of the time, the fix is one line.

Try the VIN Decoder API for free →

09FAQ

What are the most common API error codes? On ApyHub, the most common are 401 (missing or invalid key), 404 (no matching route), 405 (wrong HTTP method), 400/422 (invalid input), 429 (rate limit) and 5xx (service failure). The first three come from the request itself, so they are fixed in your code, not by retrying.

How do I fix an API 401 Unauthorized error? The gateway did not get a valid key. Send it in the apy-token header (not Authorization: Bearer), make sure the variable is not empty, and call the host for your workspace's region.

What is the difference between "missing api key" and "invalid api key"? "Missing api key" means no key arrived at all. "Invalid api key" means a key arrived but was wrong, malformed, or sent in the wrong header.

How do I fix an API 404 error when the URL looks right? Check the provider slug, service slug and endpoint path against the service page. If the error body names a missing resource, like vin_not_found, the URL is fine and the input is the problem.

How do I fix 405 Method Not Allowed? The route exists but does not accept that HTTP method. Use the method from the service page: for example, /vin/batch only accepts POST, so a GET returns 405.

Should I retry 401, 404 or 405 errors? No. The same request fails the same way. Retry only 429 and 5xx errors, with backoff.

How do I test an ApyHub API before writing code? Use the playground on the service page, run the curl commands in this post, or save the working request in Voiden, an open-source API client that stores requests as Markdown files next to your code. Once a request works there, copy it into your app unchanged.

Is there a free plan? Yes. The ApyHub Starter plan includes 5 API calls a day and 3,000 atoms a month, with no credit card.

10About API Forge

API Forge builds focused, production-ready JSON APIs for developers, each with a clear contract, sensible caching and a fallback when an upstream source fails. Besides the VIN Decoder, part of ApyHub's Verification kit, their APIs on ApyHub include:

• Crypto prices: live prices and conversion, historical prices and volume and a global market overview
• On-chain data: blockchain gas prices and DeFi protocol TVL
• Risk and sentiment: token security risk analysis and a market sentiment index
• E-invoicing: validate, generate and send Peppol e-invoices

See all of them on the API Forge provider page.

11About ApyHub

ApyHub runs a catalog of ready-made APIs that teams build their products on, so they write and maintain less of their own code and ship faster. The catalog has over 1,500 endpoints and capabilities and keeps growing, all under one subscription billed in atoms. Every service is verified, carries machine-readable certification (GDPR, SOC 2, ISO 27001), is MCP-ready by default and runs in dedicated EU and US regions, with hosting and compliance taken care of. More than 65,000 developer workspaces use ApyHub every month, and the free tier needs no credit card. Have an API of your own? Publish it on ApyHub.