--- title: "401, 404, 405: Why Your ApyHub API Calls Fail and How to Fix Them" url: https://apyhub.com/blog/fix-401-404-405-apyhub-api-errors author: API Forge published: 2026-11-10T08:18:58.959182Z tags: [best practices, how to, error, 401, 404, 405, api] --- # 401, 404, 405: Why Your ApyHub API Calls Fail and How to Fix Them ## Introduction 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](https://apyhub.com/corsair96/service/decode-and-validate-vin-api) (you can find my other APIs on my [provider page](https://apyhub.com/providers/corsair96) if you're interested), but the rules apply to every service in the [ApyHub catalog](https://apyhub.com/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. ## Anatomy of an ApyHub request Every REST call follows the same pattern: ```text METHOD https://api..apyhub.com/// ``` A real example: ```bash curl -i "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decode?vin=1HGCM82633A004352" \ -H "apy-token: $APY_TOKEN" ``` | Part | Example | What it identifies | |---|---|---| | Region host | `api.eu.apyhub.com` | Your workspace's ApyHub region | | Provider slug | `corsair96` | The publisher, not its display name | | Service slug | `decode-and-validate-vin-api` | The service, not its marketing title | | Endpoint path | `/vin/decode` | The exact route inside the service | | Method | `GET` | The verb the route accepts | | Auth header | `apy-token` | Your ApyHub API key | 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](https://apyhub.com/corsair96/service/decode-and-validate-vin-api.md). ## 401 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: `. 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: ```bash curl "https://api.eu.apyhub.com/corsair96/decode-and-validate-vin-api/vin/decode?vin=1HGCM82633A004352" \ -H "Authorization: Bearer $APY_TOKEN" ``` Right: ```bash 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. ## 404 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`. ```text # 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. ## 405 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. | Endpoint | Method | Input | |---|---|---| | `/vin/validate` | GET | `vin` query parameter | | `/vin/decode` | GET | `vin` query parameter | | `/vin/recalls` | GET | `vin` query parameter | | `/vin/batch` | POST | JSON body with a `vins` array (up to 50) | This returns 405: ```bash # 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: ```bash 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. ## The 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: ```bash 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](https://apyhub.com/corsair96/service/get-blockchain-gas-prices-transaction-fee).) ### API error codes at a glance | Status | Meaning | Action | |---|---|---| | 400 / 422 | Route matched, input is invalid | Read the error body and fix the parameter or JSON field | | 401 | Missing, invalid, or misplaced credentials | Check the `apy-token` header and region host | | 404 | No route matched, or resource missing | Check the URL parts, then inspect the error body | | 405 | Route exists, method not allowed | Use the documented method | | 429 | Rate limit or quota reached | Back off and retry later | | 5xx | Service or upstream failed | Retry with exponential backoff, then contact the provider | Do not retry 401, 404, or 405: the same request will fail the same way. Retrying only makes logs noisier. ## Skip URL building with ApyHub MCP If an AI agent makes the call, it can skip most of this. Through [ApyHub MCP](https://apyhub.com/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 →](https://apyhub.com/mcp)** ## Recap - **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 →](https://apyhub.com/corsair96/service/decode-and-validate-vin-api)** ## FAQ **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](https://voiden.md/), 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. ## About API Forge [API Forge](https://apyhub.com/providers/corsair96) 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](https://apyhub.com/corsair96/service/decode-and-validate-vin-api), part of ApyHub's [Verification kit](https://apyhub.com/catalog/verification), their APIs on ApyHub include: - Crypto prices: [live prices and conversion](https://apyhub.com/corsair96/service/convert-and-get-crypto-prices-api), [historical prices and volume](https://apyhub.com/corsair96/service/crypto-price-volume-history) and a [global market overview](https://apyhub.com/corsair96/service/get-global-crypto-market-overview-api) - On-chain data: [blockchain gas prices](https://apyhub.com/corsair96/service/get-blockchain-gas-prices-transaction-fee) and [DeFi protocol TVL](https://apyhub.com/corsair96/service/get-defi-protocol-tvl-data) - Risk and sentiment: [token security risk analysis](https://apyhub.com/corsair96/service/analyze-crypto-token-security-risks) and a [market sentiment index](https://apyhub.com/corsair96/service/crypto-market-sentiment-index) - E-invoicing: [validate, generate and send Peppol e-invoices](https://apyhub.com/corsair96/service/validate-generate-send-peppol-e-invoices) See all of them on the [API Forge provider page](https://apyhub.com/providers/corsair96). ## About ApyHub [ApyHub](https://apyhub.com/) 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](https://apyhub.com/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](https://apyhub.com/api-provider).