Errors - Matter Documentation

The API uses standard HTTP status codes and returns structured JSON error bodies.

Error format

Every error response has this shape:

{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123.",
    "field": null
  }
}

Field	Type	Description
`code`	string	Machine-readable error code for programmatic handling.
`message`	string	Human-readable description of what went wrong.
`field`	string \| null	The request field that caused the error, when applicable.

HTTP status codes

Status	Meaning	When you’ll see it
`200`	OK	Successful read or update.
`201`	Created	Successfully created a new resource.
`204`	No Content	Successful delete.
`400`	Bad Request	Invalid request body, missing required field, or malformed parameter.
`401`	Unauthorized	Missing or invalid API token.
`403`	Forbidden	Valid token but insufficient permissions (e.g., no Pro subscription).
`404`	Not Found	The requested resource doesn’t exist or doesn’t belong to your account.
`409`	Conflict	Resource already exists (e.g., duplicate tag name).
`422`	Unprocessable Entity	Request is well-formed but semantically invalid (e.g., invalid URL).
`429`	Too Many Requests	Rate limit exceeded. See rate limits.
`500`	Internal Server Error	Something went wrong on our end. Retry with backoff.

Error codes

Code	Status	Description
`bad_request`	400	Generic invalid request.
`validation_error`	400	A specific field failed validation. Check `field`.
`unauthorized`	401	Invalid or missing API token.
`forbidden`	403	Pro subscription required, or resource not accessible.
`not_found`	404	Resource not found or not owned by you.
`conflict`	409	Resource already exists.
`unprocessable`	422	Request is syntactically valid but can’t be processed.
`rate_limited`	429	Too many requests. Check `Retry-After` header.
`internal_error`	500	Server error. Retry with exponential backoff.

Validation errors

When a specific field is invalid, the field property tells you which one:

{
  "error": {
    "code": "validation_error",
    "message": "URL must start with http:// or https://.",
    "field": "url"
  }
}

Handling errors

response = requests.post(url, headers=headers, json=data)

if response.status_code >= 400:
    error = response.json()["error"]
    if error["code"] == "rate_limited":
        retry_after = int(response.headers["Retry-After"])
        time.sleep(retry_after)
    elif error["code"] == "validation_error":
        print(f"Fix field '{error['field']}': {error['message']}")
    else:
        print(f"Error: {error['message']}")