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

```json
{
  "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.