Errors and restrictions
This page describes how the V60 Brew Log API reports errors and which restrictions apply to requests and field values.
Error format
When a request fails, the API returns an HTTP status code and a JSON object with a single error field:
{
"error": "cupId is not found"
}
Use the HTTP status code to handle errors in your application. The error message is meant for people, and its wording can change, so don't parse it.
Status codes
| Code | Meaning | Example message | What to do |
|---|---|---|---|
400 Bad Request | A query parameter or a body field is missing or invalid. | date format must be YYYY-MM-DD | Check the request against the restrictions and the API reference, then fix the request. |
401 Unauthorized | The X-API-Key header is missing. | Header must contain API-Key | Add the API key to the request. See Getting started. |
404 Not Found | A record with the specified ID doesn't exist. | cupId is not found | Check the ID. The record might have been deleted. |
The messages in the table are examples. The actual message describes the specific problem with your request.
Restrictions
Number of records
List requests return up to 50 records by default. To change the number of records, use the limit query parameter. It accepts values from 1 to 100.
The API doesn't support offset or cursor pagination. A list request returns at most 100 records.
Field values
If a value is outside the allowed range or has the wrong format, the API returns 400 Bad Request.
| Resource | Field | Allowed values |
|---|---|---|
| All | limit query parameter | Integer from 1 to 100 |
| Cup | date | Date in the YYYY-MM-DD format |
| Cup | rating field and query parameter | Integer from 1 to 10 |
| Cup | taste.body, taste.sourness, taste.bitterness | Integer from 1 to 10 |
| Bean | roastDate | Date in the YYYY-MM-DD format |
| Recipe | waterTemp | Integer from 90 to 100 (°C) |
| Recipe | brewTime | Integer, in seconds |
| Recipe | spin | Boolean |
Required fields
When you create or replace a record, include all required fields. Otherwise, the API returns 400 Bad Request.
| Resource | Required fields |
|---|---|
| Cup | date, beanId, recipeId, rating |
| Bean | origin, name, roaster |
| Recipe | grindSize, ratio, waterTemp, brewTime |
Rate limits
The API doesn't limit the number of requests.
Test errors in the sandbox
The sandbox doesn't store data, so it returns successful responses for most requests. You can still test how your application handles errors.
To get 400 Bad Request, send an invalid value:
curl "https://brewlog-api.bellsandthistl.es/cups?rating=11" \
-H "X-API-Key: my-test-key"
To get 401 Unauthorized, send a request without the X-API-Key header:
curl https://brewlog-api.bellsandthistl.es/cups
To get any status code that the endpoint supports, such as 404 Not Found, add the Prefer header with the code:
curl https://brewlog-api.bellsandthistl.es/cups/1 \
-H "X-API-Key: my-test-key" \
-H "Prefer: code=404"
An error response can have several examples, one for each cause of the error. The API reference lists them for every endpoint. To get a specific example, add its name to the Prefer header:
curl https://brewlog-api.bellsandthistl.es/cups \
-H "X-API-Key: my-test-key" \
-H "Prefer: code=400, example=limitOutOfRange"
The sandbox doesn't detect which parameter or field is invalid. For an invalid request, it returns the first example of the error response, whatever the actual cause. For example, GET /cups?limit=500 returns rating must be between 1 and 10. To get the message for a specific cause, send a valid request with the Prefer header, as shown above.