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:
{
"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"
}
]
}
typeis a URL that points to the matching section on this page.codeis stable: branch on it, not ontitleordetail, which may be reworded.errors[]appears on400responses and names each parameter at fault.- Error responses carry the same
RateLimitheaders as successful ones, and429addsRetry-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 and the sitemap.
All codes
| Code | HTTP status | Meaning |
|---|---|---|
missing_parameter |
400 | A required query parameter was not sent. |
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 |
404 | No page, API resource, state or statistic exists at that path or id. |
method_not_allowed |
405 | The API is read-only, so only GET, HEAD and OPTIONS are accepted. |
rate_limited |
429 | More than 60 requests arrived from your IP address within 60 seconds. |
prices_not_published |
503 | The cost estimate is switched off while its published price ranges are being re-verified. |
unavailable |
503 | The data behind the operation could not be loaded, usually for a few seconds after a deploy. |
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: 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: 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: Connect an AI assistant to Valet Trash Guide over MCP (Streamable HTTP): search guides, read pages, get state rules, cite statistics, estimate costs.