Listing an API on RapidAPI: five things the docs don't cover

I spent two weeks putting a PDF processing API on RapidAPI. The code was the
easy part: twelve endpoints that already worked, serving a website. What cost
me the time was the gateway, and almost none of it is in the documentation.

1. The gateway routes only the endpoints you declare

My origin server has twelve endpoints. I defined four in RapidAPI's dashboard
to get the listing live, assuming the gateway was a dumb proxy that would
forward whatever path came through.

$ curl -X POST "https://...p.rapidapi.com/ocr-pdf" -H "X-RapidAPI-Key: $KEY" ... {"message":"Endpoint '/ocr-pdf' does not exist"} 

Eight of my twelve endpoints were unreachable. I had already written the
documentation for all twelve. Had I published it, every subscriber would have
hit a 404 on two thirds of the product.

Declare every endpoint before you write a line of docs.

2. An undeclared path returns 401, not 404

This is what made the first one hard to catch.

I probed the gateway without a key, expecting a missing endpoint to 404:

$ curl -X POST "https://...p.rapidapi.com/definitely-not-real" 401 $ curl -X POST "https://...p.rapidapi.com/compress" # this one is declared 401 

Identical. Authentication runs before path resolution, so an undeclared
path is indistinguishable from a declared one until you authenticate.

The practical consequence: you cannot audit your own gateway without a valid
subscriber key. I spent an hour reasoning from 401s that could not tell me
anything, then subscribed to my own free tier and got the answer in one
request.

Subscribe to your own API and call every endpoint end to end. Not the test
console in the dashboard, but a real request with a real key from outside.

3. Your paying customers will throttle each other

RapidAPI proxies every request through its own IP addresses.

My rate limiter was keyed on client IP. Ten requests a minute per IP, which is
correct for a public website. Behind the gateway, every paying subscriber in
the world shares that same handful of proxy IPs.

Customer A's traffic would have consumed Customer B's limit. The first two
subscribers would have 429'd each other and churned, and I would have had no
idea why.

The gateway does tell you who the request belongs to, in X-RapidAPI-User. But
anyone can set that header by hand, so it means nothing on its own. What makes
it trustworthy is the shared proxy secret RapidAPI sends alongside it:

func (a *RapidAPIAuth) ServeHTTP(w http.ResponseWriter, r *http.Request) { sent := r.Header.Get("X-RapidAPI-Proxy-Secret") claimsRapid := sent != "" || r.Header.Get("X-RapidAPI-User") != "" if !claimsRapid { a.next.ServeHTTP(w, r) // ordinary web traffic, leave it alone return } // Constant-time, because == leaks the secret's length and prefix. if subtle.ConstantTimeCompare([]byte(sent), []byte(a.secret)) != 1 { http.Error(w, "invalid RapidAPI proxy secret", http.StatusForbidden) return } user := r.Header.Get("X-RapidAPI-User") if user == "" { // Verified as RapidAPI but unattributable. Refusing beats billing it // to the shared IP bucket. http.Error(w, "missing X-RapidAPI-User", http.StatusBadRequest) return } ctx := context.WithValue(r.Context(), rapidUserKey{}, user) a.next.ServeHTTP(w, r.WithContext(ctx)) } 

Then key your limiter on the subscriber instead of the IP. Headers that claim
RapidAPI without the secret get rejected rather than trusted, which closes the
obvious forgery.

4. You cannot lower the advertised rate limit

I had measured what the box does: 144 conversions an hour on a t3.micro, five
concurrent requests comfortable. So the server enforces 120 requests an hour per
subscriber, a number the hardware can actually serve.

RapidAPI does not let you. Paid tiers are fixed at 1,000 requests per hour and
there is no field to change it. The platform advertises a number my server
cannot serve.

There is no technical fix. The honest resolution is to enforce the real number
server-side and say so in the docs, before someone subscribes:

The rate column shows what you can sustain. RapidAPI's plan page says 1,000
requests per hour on the paid tiers because the platform gives a provider no
way to lower that number; our own limit is 120 per hour per subscription.

Better a customer reads that on the pricing page than discovers it at request
121.

5. The OpenAPI importer may not work

Twelve endpoints, a valid OpenAPI 3.0.3 spec, and an importer that advertises
OpenAPI 3.0.3. This should have been one upload.

An error occurred Cannot read properties of null (reading 'getChildGroups') 

I converted YAML to JSON. Same class of failure, one step further in:

Cannot read properties of null (reading 'appendChild') 

I stripped the tags in case it was choking on group creation. Still failed. I
tried the file upload, the remote URL and the paste-text tabs. All three.

In the end I added twelve endpoints by hand, each with its method, path,
description and form fields. Roughly two minutes apiece.

Budget for that. If the importer works for you, you saved half an hour. If it
does not, you have not lost an afternoon discovering that it will not.

What I would do differently

In order:

1. Declare every endpoint in the dashboard first, by hand, assuming no import.
2. Subscribe to your own free tier and call every endpoint from outside.
3. Check your rate limiting is keyed on the subscriber, not the IP.
4. Measure what your hardware does, then document that number rather than the one the platform shows.
5. Write the documentation last, against endpoints you have called yourself.

None of this is hard. It stays invisible until you are live, which is the worst
time to find it.

The API is Papyrio PDF Tools;
the reference is at papyrio.net/docs. Free tier is
50 requests a month, no card. Here is the whole path from sign-up to a first
compressed PDF, about a minute:

The same twelve endpoints also run as an MCP server, so Claude, Cursor or VS Code
can call them on local files. This is the install in Claude Desktop, 47 seconds: