Errors and recovery

The v2 API returns OAuth error bodies for OAuth flows and structured error envelopes for v2 resource requests.

Error shapes

OAuth
v2 API

OAuth endpoints return error and error_description.

Response

{
  "error": "invalid_scope",
  "error_description": "Scope not allowed for this application: products.write"
}

v2 endpoints return success, code, and message when a structured error body is available.

Response

{
  "success": false,
  "code": "insufficient_scope",
  "message": "Token must include one of: products.write"
}

Common status codes

Status	Meaning	Recovery
`400`	The request body, query, or OAuth grant is invalid.	Validate field names, required properties, and OAuth form fields.
`401`	Credentials are missing, invalid, or cannot authenticate the request.	Check Basic auth, client headers, bearer tokens, and rotated secrets.
`403`	The credential is valid but lacks an accepted scope.	Add the required scope to the application or token request.
`404`	The requested resource does not exist for the tenant.	Re-read the list endpoint and use the returned resource ID.
`409`	The requested archive operation conflicts with current state.	Read the record, resolve dependent state, then retry when safe.

Recovery playbooks

A write request returns 403

Confirm that the developer application has the write scope for that resource. Then confirm the token request included that scope if you are using bearer tokens.

A product create request returns 400

Check that the request includes name and at least one entry in variations. Verify field names use snake_case and enum values match the API reference.

A resource lookup returns 404

The ID may belong to another tenant, may be archived outside the active view, or may not exist. Re-list the resource with the relevant filters before retrying.

An archive request returns 409

A product variation archive can conflict with current product state. Re-read the product and archive records in the order required by your workflow.

Error handling example

async function invoiceEdgeJson(response) {
  const text = await response.text();
  const body = text ? JSON.parse(text) : null;

  if (!response.ok) {
    const detail = body?.message || body?.error_description || response.statusText;
    throw new Error(`Vantr ${response.status}: ${detail}`);
  }

  return body;
}

def invoice_edge_json(response):
    try:
        body = response.json()
    except ValueError:
        body = None

    if not response.ok:
        detail = None
        if isinstance(body, dict):
            detail = body.get("message") or body.get("error_description")
        raise RuntimeError(f"Vantr {response.status_code}: {detail or response.reason}")

    return body

Log the HTTP status, endpoint, and safe error body fields. Do not log client secrets, bearer tokens, or full authorization headers.

Start

Build

Operate

Errors and recovery

Errors and recovery

Error shapes

Common status codes

Recovery playbooks

Error handling example

​Errors and recovery

​Error shapes

​Common status codes

​Recovery playbooks

​Error handling example

Errors and recovery

Error shapes

Common status codes

Recovery playbooks

Error handling example