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"
    }
  ]
}
  • 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 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.