API error reference

The API answers every failure with an RFC 9457 problem document, media type application/problem+json. The `type` member of each problem links to the matching section on this page.

Shape#

Every problem document carries type, title, status and code. Most also carry detail explaining this occurrence, and resolution telling you what to do about it. Ignore members you do not recognise, as RFC 9457 requires, because more may be added.

{
  "type": "https://voxgig.com/developers/errors#missing_fields",
  "title": "Missing required fields",
  "status": 400,
  "code": "missing_fields",
  "detail": "name, email and message are all required.",
  "instance": "/api/contact",
  "resolution": "Send all three fields as JSON or form data, then retry.",
  "errors": [{ "field": "email", "message": "required" }]
}

not_found#

HTTP 404. The path does not exist. This is a real 404, never a 200 carrying an app shell, so you can trust it.

Fix: check the path against the sitemap at /sitemap-index.xml or the OpenAPI description at /openapi.json.

not_acceptable#

HTTP 406. The Accept header excludes every representation the resource can produce. The available member lists what it can produce.

Fix: send an Accept header naming one of the available media types, or omit Accept entirely to get the default.

method_not_allowed#

HTTP 405. The endpoint does not support that HTTP method. The Allow response header and the allowed member both list the methods it does support.

Fix: retry with an allowed method. The MCP endpoint, for example, is POST only.

unsupported_media_type#

HTTP 415. The request Content-Type is one the endpoint cannot parse.

Fix: send application/json, or application/x-www-form-urlencoded where the endpoint documents it.

invalid_request#

HTTP 400. The request was understood but a parameter is out of range or malformed. The detail member names the parameter.

Fix: correct the parameter against the schema in /openapi.json and retry.

invalid_json#

HTTP 400. The body was declared as JSON but did not parse.

Fix: check for a truncated body or a trailing comma, then retry. Retrying the identical body will fail identically.

missing_fields#

HTTP 400. A required field was absent or empty. The errors member lists each offending field.

Fix: supply every field named in errors and retry.

payload_too_large#

HTTP 413. The request body is larger than the endpoint accepts.

Fix: shorten the body. The contact message field accepts up to 5000 characters.

unauthorized#

HTTP 401. You called an administrative endpoint. Those are for site operators and are not part of the public API.

Fix: nothing to do. No public endpoint requires authentication, so if you are seeing this you are calling the wrong path.

server_error#

HTTP 500. Something failed on our side. The response deliberately carries no implementation detail.

Fix: retry once after a short pause. If it persists, email info@voxgig.com with the path and the time.