Errors & status codes

When a request fails, InsurGrid returns one consistent JSON shape, no matter which endpoint you called. Learn this envelope once and you can handle every error the same way.

The error envelope

{
  "message": "Slug is already in use for this agency.",
  "code": "form_slug_conflict",
  "request_id": "req_7a1c9e2b4f",
  "errors": [
    { "field": "slug", "message": "must be unique" }
  ]
}

Field	Type	Meaning
message	string	A human-readable description of what went wrong. Safe to log or show in an internal tool.
code	string	A stable, machine-readable error code — branch on this in code, not on message, since wording can change.
request_id	string	A unique id for this specific request. Always log it.
errors[]	array	Present on validation failures (422). One entry per invalid field: field and message.

New term — request_id: every API call gets a unique id, returned on both success and failure. It's how InsurGrid support finds your exact request in their logs — quote it (or a webhook payload's trace_id) whenever you contact support.

Status codes

Status	Meaning	What to do
400	Malformed request — bad JSON, missing required parameter.	Fix the request shape.
401	Missing or invalid API token.	Check your Authorization: Bearer <token> header.
403	Authenticated, but not permitted (e.g. an ordinary agent trying to create a form).	Check the ownership model — the caller may need an owner/admin token.
404	Not found, or outside your account's visibility.	Check the id, and that the resource belongs to your account.
409	Conflict — e.g. a duplicate slug, or an invalid status transition (like publishing an already-archived form).	Read message for specifics; don't blindly retry.
422	Validation failed.	Walk errors[] and fix each field.
429	Rate limited.	Back off using Retry-After — see Rate limits.

Always log request_id

Log request_id (and trace_id, when the payload has one — see Webhook events & payloads) alongside every failed call. If you need to contact InsurGrid support, quoting it lets them find the exact request instead of guessing from a timestamp.

Node:

const res = await fetch("https://api.insurgrid.com/v2/forms", {
  headers: { Authorization: `Bearer ${token}` },
});

if (!res.ok) {
  const err = await res.json();
  console.error(`InsurGrid error [${err.code}] request_id=${err.request_id}: ${err.message}`);
}

Python:

resp = requests.get(
    "https://api.insurgrid.com/v2/forms",
    headers={"Authorization": f"Bearer {token}"},
)

if not resp.ok:
    err = resp.json()
    print(f"InsurGrid error [{err['code']}] request_id={err['request_id']}: {err['message']}")

Related

• Rate limits

• Pagination (cursors)

• Ownership model (agency vs agent)

• Troubleshooting

• Support