Troubleshooting

Authentication and access

401 Missing API key

The Authorization header is missing or doesn't start with Bearer (with the space). Check for proxies that strip headers.

401 Invalid or revoked API key

• The key was revoked. Check Dashboard → API Keys.
• The key is truncated or has extra whitespace or a newline from copy-paste or your secrets tooling.
• The value doesn't start with rwc_, so it isn't an API key.

402 A payment method must be on file… or 402 The free trial ended on…

Your free trial has ended, or there's no payment method on file. Add a card under Dashboard → Payments. Your existing keys work again as soon as it's saved.

403 …cancelled / suspended / disabled

The error message tells you why:

Socket won't connect

Listen for connect_error and log err.message. It gives the same reasons as above. Also check that you're passing auth: { apiKey }, not a header, and that your network allows WebSocket upgrades to the API host.

Matching

Matches are always unmatched

Work through this list:

1. Is anyone online? Check that your backend is sending agent:location with status: "available" and getting { ok: true } acknowledgements.
2. Are they fresh? Each agent needs a location in the last 30 seconds. Agents who stopped sending locations are skipped.
3. Does vehicleType match exactly? "Sedan" ≠ "sedan".
4. Are they within range? The default radius is 10 km. Try a larger radiusMeters, up to 50 km.
5. Are lat and lng the right way round? A swapped pair puts agents on the other side of the world.
6. Are they already on another offer? An agent holding an offer for another match is skipped until it resolves.

An agent on a trip keeps getting offers

Your location updates are sending no status, or available, while they're on the trip. Send status: "busy" for the whole trip. See Agent tracking.

ride:respond returns Offer is no longer active

The agent answered too late (after 15 s), the match was cancelled, or the offer was already resolved. This is expected occasionally. Tell the agent the offer is gone. To reduce how often it happens, show agents a countdown a couple of seconds shorter than expiresInMs.

I received ride:offer before the POST /matches response

Expected. The first offer is sent while the request is still being handled. Track offers by matchId.

409 when cancelling

• …can no longer be cancelled: the match already finished. Read it with GET /matches/{id} to see whether an agent accepted.
• …retry shortly: an agent answer or timeout was being processed at that moment. Retry after a brief pause.

Tracking and billing

My active agent count is higher than expected

Agents count as active until you send status: "offline" or they go 30 seconds without sending a location. If your app keeps sending locations for agents who have finished their shift, they still count. Send offline when an agent signs off.

429 Too Many Requests

You went over 300 REST requests per minute for one key. Use the socket instead of polling, back off using retry-after, and use match:update instead of polling GET /matches/{id}.

Still stuck?

Contact RideWiseCore support with:

• The approximate time (UTC) of the problem.
• The matchId or agentId involved.
• The full error message and statusCode.

Never send your full API key. The first few characters, or its label, are enough.