---
title: "Errors — Tiny Plates recipe API"
description: "Every error the Tiny Plates API can return, the JSON envelope they all share, the status codes they use, and what to do about each one."
url: "https://www.tinyplates.dev/docs/errors"
---

# Errors

Every error has the same shape and a message written to be read by a person. The status code says what kind of problem it is; the message says what to do about it.

## The envelope

Whatever goes wrong, the body is the same object. There is no error code to switch on — branch on the HTTP status, and show the message.

```
{
  "error": {
    "message": "Recipe not found."
  }
}
```

An unmatched path answers `404` with the same envelope: `No such endpoint. See /docs for the available routes.`

## Bad requests

A parameter the API cannot use is rejected rather than ignored, so a typo shows up as an error instead of an empty page. The message names the parameter, the value it was given, and where the allowed values are listed.

* 400  
The query parameter is required.  
The \`query\` parameter was missing or empty.
* 400  
Unknown cuisine "italien". The allowed values are listed by GET /vocabularies.  
A parameter was not a value the API accepts. The message names the parameter, the value it was given and where the allowed values are listed.
* 400  
The "limit" parameter must be a whole number of at least 1; got "many".  
A parameter was not a value the API accepts. The message names the parameter, the value it was given and where the allowed values are listed.
* 400  
The "language" parameter must be a two-letter code such as "en" or "sv"; got "english".  
A parameter was not a value the API accepts. The message names the parameter, the value it was given and where the allowed values are listed.
* 400  
The "category" parameter must be a slug such as "main-course" or "chicken-thigh"; got "Main Course".  
A parameter was not a value the API accepts. The message names the parameter, the value it was given and where the allowed values are listed.

The closed vocabularies are on [filtering and vocabularies](https://www.tinyplates.dev/docs/filtering), and served live by [GET /vocabularies](https://www.tinyplates.dev/docs/api/vocabularies).

## Keys

* 401  
An API key is required. Pass it as an Authorization: Bearer header.  
No key was sent. Every endpoint except the root, /health, /docs and /openapi.json requires one.
* 401  
Invalid API key.  
The key does not exist. Check for a truncated copy, or create a new one on your dashboard.
* 401  
This API key has been disabled.  
The key was revoked. Create a new one on your dashboard.
* 401  
This API key has expired.  
The key was created with an expiry that has passed. Create a new one.
* 429  
Daily allowance of 50 requests used. It resets at midnight UTC. Paid plans include more; see https://www.tinyplates.dev/pricing.  
The account has used its 50 requests for the day. The allowance is per account, so another key will not help. It resets at midnight UTC.
* 429  
Weekly allowance of 300 requests used. It covers the last 7 days. Paid plans include more; see https://www.tinyplates.dev/pricing.  
The account has used its 300 requests over the last 7 days, today included. The allowance is per account, so another key will not help. Room comes back as older days drop out of the window.
* 429  
Daily limit of 5,000 requests on the Personal plan reached. It resets at midnight UTC. Contact us for a higher limit.  
The account has used its plan's limit for the day. The message names the number and the plan, which differ between accounts. The limit is per account, so another key will not help. It resets at midnight UTC.
* 429  
Weekly limit of 30,000 requests on the Business plan reached. It covers the last 7 days. Contact us for a higher limit.  
The account has used the weekly limit set on it over the last 7 days, today included. The message names the number and the plan. Only accounts with a weekly limit can see this. Room comes back as older days drop out of the window.

See [authentication](https://www.tinyplates.dev/docs/authentication) for how a key is sent, and [rate limits](https://www.tinyplates.dev/docs/rate-limits) for the 429.

## Missing things

* 404  
Recipe not found.  
No recipe has that id. Ids are opaque strings from a list or search response, not slugs.

## Our fault

* 500  
Something went wrong. Please try again.  
The API could not answer. The request was not your fault; retry it, and report it if it keeps happening.

A 500 is never caused by the request. Retrying is reasonable — once, after a short pause. If it keeps happening, the request was fine and we want to hear about it.