---
title: "Valet Trash Guide API error codes"
description: "Every error the Valet Trash Guide API returns, as RFC 9457 problem+json: what each code means and how to fix the request."
canonical: "https://valettrashguide.com/developers/errors/"
last-updated: "2026-11-15"
author: "Valet Trash Guide Editorial Team"
publisher: "Valet Trash Guide"
license: "Quote with attribution and a link to the canonical URL."
---
# API error codes

> Every error is an RFC 9457 problem+json document with a stable code. Each code below is the anchor its type URI points to.

## Format

Every API error is an RFC 9457 problem details document, served as `application/problem+json`:

```json
{
  "type": "https://valettrashguide.com/developers/errors/#missing_parameter",
  "title": "Missing parameter",
  "status": 400,
  "detail": "Add a q parameter with your keywords, for example /api/v1/search?q=fire+code+texas",
  "instance": "/api/v1/search",
  "code": "missing_parameter",
  "errors": [
    {
      "parameter": "q",
      "detail": "Add a q parameter with your keywords, for example /api/v1/search?q=fire+code+texas"
    }
  ]
}
```

- `type` is a URL that points to the matching section on this page.
- `code` is stable: branch on it, not on `title` or `detail`, which may be reworded.
- `errors[]` appears on `400` responses and names each parameter at fault.
- Error responses carry the same `RateLimit` headers as successful ones, and `429` adds `Retry-After`.

Outside the API, a missing page requested with `Accept: application/json` gets a `not_found` problem, and one requested with `Accept: text/markdown` gets a short Markdown page that links to [/llms.txt](https://valettrashguide.com/llms.txt) and the [sitemap](https://valettrashguide.com/sitemap.xml).

## All codes

| Code | HTTP status | Meaning |
| --- | --- | --- |
| [`missing_parameter`](#missing_parameter) | 400 | A required query parameter was not sent. |
| [`invalid_parameter`](#invalid_parameter) | 400 | A parameter was sent but its value is outside what the operation accepts: wrong type, out of range, not in the allowed list, or a cursor that was not issued by this API. |
| [`not_found`](#not_found) | 404 | No page, API resource, state or statistic exists at that path or id. |
| [`method_not_allowed`](#method_not_allowed) | 405 | The API is read-only, so only GET, HEAD and OPTIONS are accepted. |
| [`rate_limited`](#rate_limited) | 429 | More than 60 requests arrived from your IP address within 60 seconds. |
| [`prices_not_published`](#prices_not_published) | 503 | The cost estimate is switched off while its published price ranges are being re-verified. |
| [`unavailable`](#unavailable) | 503 | The data behind the operation could not be loaded, usually for a few seconds after a deploy. |
| [`internal_error`](#internal_error) | 500 | An unexpected error happened while answering the request. |

## missing_parameter

HTTP 400, "Missing parameter". A required query parameter was not sent.

How to fix: Add the parameter named in `errors[].parameter`. For example, search needs `q` and the estimate needs `units`.

## invalid_parameter

HTTP 400, "Invalid parameter". A parameter was sent but its value is outside what the operation accepts: wrong type, out of range, not in the allowed list, or a cursor that was not issued by this API.

How to fix: Read `errors[].detail` for the accepted values, correct the value and retry. Pass `cursor` exactly as returned in `pagination.next_cursor`.

## not_found

HTTP 404, "Not found". No page, API resource, state or statistic exists at that path or id.

How to fix: Check the path against https://valettrashguide.com/openapi.json, or search with GET /api/v1/search?q=... to find the right resource.

## method_not_allowed

HTTP 405, "Method not allowed". The API is read-only, so only GET, HEAD and OPTIONS are accepted.

How to fix: Send a GET request. The `Allow` response header lists the accepted methods.

## rate_limited

HTTP 429, "Too many requests". More than 60 requests arrived from your IP address within 60 seconds.

How to fix: Wait the number of seconds in the `Retry-After` header, then retry. The `RateLimit` header shows how many requests remain in the current window.

## prices_not_published

HTTP 503, "Prices not published". The cost estimate is switched off while its published price ranges are being re-verified.

How to fix: Retry later, or read the sourced ranges on https://valettrashguide.com/tools/valet-trash-cost-calculator/.

## unavailable

HTTP 503, "Temporarily unavailable". The data behind the operation could not be loaded, usually for a few seconds after a deploy.

How to fix: Retry after a short wait. The static files under /api/v1/*.json stay available.

## internal_error

HTTP 500, "Internal error". An unexpected error happened while answering the request.

How to fix: Retry once. If it keeps happening, tell the editors at https://valettrashguide.com/contact/ and include the request URL.

## More developer docs

- [Valet Trash Guide for developers and AI agents](https://valettrashguide.com/developers/): Free, read-only access to valet trash guides, state rules, sourced statistics and cost estimates: JSON API, MCP server, WebMCP and Markdown. No key.
- [Valet Trash Guide API](https://valettrashguide.com/developers/api/): Free, read-only JSON API for valet trash guides, state rules, statistics and cost estimates: operations, examples, pagination, rate limits and errors.
- [Valet Trash Guide MCP server](https://valettrashguide.com/developers/mcp/): Connect an AI assistant to Valet Trash Guide over MCP (Streamable HTTP): search guides, read pages, get state rules, cite statistics, estimate costs.
