Voxgig API error reference

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 true 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.

challenge_failed#

HTTP 403. A form submission arrived without a valid Cloudflare Turnstile token, or with one that had already been used. The two public forms, https://voxgig.com/contact and https://voxgig.com/jobs, both require one: they reach a person, and the challenge is what keeps the volume of what that person reads human.

Fix: submit the form in a browser at https://voxgig.com/contact or https://voxgig.com/jobs, where the challenge is solved for you. A token is single-use and expires, so a replayed one is refused; reload the page and submit again. There is no way to obtain a token programmatically, by design. An agent should hand the URL to the person it is helping, or use the email addresses published on https://voxgig.com/contact.

rate_limited#

HTTP 429. Too many submissions arrived from one address in a short window. The catalogue and documentation endpoints are not rate limited; this applies only to the two forms that write to a database.

Fix: wait a minute and submit again. The Retry-After header says how long. If you have a legitimate need for volume, email info@voxgig.com rather than working around it.

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.

API error reference