Errors and limits
The cause behind each HTTP status, the API rate limit, and error handling in the SDK.
Delivery API errors come back as an HTTP status and a JSON message. Use the message to investigate the cause, and branch on the status in your app.
{ "message": "An API key is required." }What to check by status
| Status | Common cause | What to do |
|---|---|---|
400 | The query's format, value, or operator is invalid | Read the message and reduce the parameters to check |
401 | The API key is missing, invalid, before or after its validity period, or lacks the permission | Check your environment variable and the issued key |
403 | The key doesn't match the workspace | Connect to the workspace that issued it |
404 | The workspace, API, or entry doesn't exist, the API is outside the key's scope, or the entry isn't in a fetchable publish state | Check the ID, the format, the publish period, and the preview key |
429 | You exceeded the rate limit for the same API key | Stop running requests back to back and retry after a pause |
500 | Processing failed inside the server | Check again after a while, and contact us if it continues |
The API key is checked before the workspace. A request without a key returns 401, even if the workspace doesn't exist. With a valid key, a nonexistent workspace returns 404. Accessing an API outside the API key's scope also returns 404.
If an entry exists but is unpublished, a regular single-entry request returns 404. A list search with no results isn't an error. You get 200 and an empty array.
In a request with a language, an unconfigured language code, an additional language on an API that isn't multilingual, an invalid lang_fallback, or an unknown include key returns 400. Check the language code and the API's multilingual setting. If the language version you asked for isn't created or isn't published, single and object requests return 404, and a list returns 200 without that entry. To get the live main language instead, pass lang_fallback=true.
Rate limit
The delivery API limit is 300 requests per minute per API key. If you send many requests in parallel, you can hit the limit even with few entries.
- Combine repeated fetches of the same content.
- Use a cache that suits the purpose.
- Keep concurrency low for builds and bulk fetches.
- If you retry, cap the number of attempts and increase the wait.
The API doesn't return response headers that show the remaining quota or when to retry.
The SDK has no built-in automatic retry. getAll() also sends several requests internally. Don't add more keys to get around the limit.
Handle errors in the SDK
An error response from the API becomes a GenkoApiError. Failures where no HTTP response arrives, such as a network outage, can surface as a different exception.
import { GenkoApiError } from "@genko-me/sdk";import { genko } from "@/lib/client";
try { const result = await genko.apis.blog.list(); console.log(result.totalCount);} catch (error) { if (error instanceof GenkoApiError) { console.error("genko API error", error.status, error.message); } throw error;}If you want to treat only a 404 on a detail page as missing, use getOrNull(). Authentication and server errors don't become null. They're thrown as exceptions.
What we need to investigate
If you can't solve it, email [email protected] with when it happened, the workspace and endpoint, the HTTP status, the message, and the steps to reproduce. Don't send API keys, passwords, or URLs that contain a preview key.
For dashboard and settings problems, see Troubleshooting.
Last updated: October 16, 2026