On this page
At a glance#
The gateway answers its own errors with a JSON body holding a message field, and every response carries an X-Kong-Request-Id header. Errors raised by the provider's own service are passed through unchanged.
{
"message": "No active subscription for this product"
}Responses from the gateway#
| Code | Message | Meaning, and what to do |
|---|---|---|
403 | No active subscription for this product | The app has no active subscription to this product, or the subscription is not active, or the key is wrong. Check the key and the subscription. |
403 | Subscription quota exceeded | The subscription's quota for the billing period is used up. Do not retry. |
429 | Endpoint quota exceeded | The endpoint's quota is used up. Do not retry. |
404 | no Route matched with those values | No route matches the request. Check the gateway address, the version prefix and the endpoint path. |
503 | Subscription service unavailable | A gateway dependency is temporarily unavailable. Retry with backoff. |
500 | Route configuration error | The route is misconfigured on the platform side. Contact support and quote the request ID. |
Retries with backoff and jitter#
Retry only temporary failures (network errors and 502, 503 or 504 responses), at most three times, with a random interval. Otherwise all your clients retry at the same instant and create a second wave.
async function call(fn, tries = 3) { for (let i = 0; i < tries; i++) { const res = await fn(); // retry temporary failures only: not an exhausted quota, not a missing subscription if (![502, 503, 504].includes(res.status) || i === tries - 1) return res; await new Promise((r) => setTimeout(r, 2 ** i * 1000 + Math.random() * 400)); } }
When you need support#
Send the X-Kong-Request-Id value from the response when you contact support, so the call can be found (get help).
One error envelope with an error code, a message and the request ID in the body; Retry-After on throttling responses; messages in Arabic or English by Accept-Language; and an Idempotency-Key header for safe retries of POST requests.