Errors

When a request fails, Vetnio answers with an HTTP status code and a JSON body that says what went wrong. Branch on the status and the code, show or log the message, and use the retry rules at the end of this guide to decide whether to try again.

The error object

Every error from a Vetnio endpoint has the same shape. This one comes from renaming a consultation that was deleted:

{
  "message": "You cannot modify this consultation",
  "code": "FORBIDDEN",
  "data": {
    "code": "FORBIDDEN",
    "httpStatus": 403,
    "path": "consultations.rename",
    "zodError": null,
    "reason": "archived_consultation"
  }
}

Responses are always JSON with Content-Type: application/json, including errors. Two exceptions come from the hosting platform rather than from Vetnio and are not in this format: a request that runs longer than 10 minutes (504), and a request body that is too large (413). See Limits.

Status codes

Endpoints that talk to a practice system can also pass that system's failures through, for example 401 when the Vettigo session has expired or 429 when Vettigo itself rate limits. Practice systems covers those.

Validation errors

When the input does not match the endpoint's schema, the response is 400 with message Input validation failed. issues lists every problem, and path in each issue names the field. Here page and pageSize are out of range on GET/workspaces/{workspaceId}/patients:

curl "https://vetnio.com/api/v2/workspaces/demo-north-clinic/patients?page=0&pageSize=1000" \
  -H "Authorization: Bearer $VETNIO_API_KEY"

{
  "message": "Input validation failed",
  "code": "BAD_REQUEST",
  "data": {
    "code": "BAD_REQUEST",
    "httpStatus": 400,
    "path": "patientsAndClients.listPatientsV1",
    "zodError": {
      "formErrors": [],
      "fieldErrors": {
        "page": ["Too small: expected number to be >=1"],
        "pageSize": ["Too big: expected number to be <=100"]
      }
    }
  },
  "issues": [
    {
      "origin": "number",
      "code": "too_small",
      "minimum": 1,
      "inclusive": true,
      "path": ["page"],
      "message": "Too small: expected number to be >=1"
    },
    {
      "origin": "number",
      "code": "too_big",
      "maximum": 100,
      "inclusive": true,
      "path": ["pageSize"],
      "message": "Too big: expected number to be <=100"
    }
  ]
}

Each issue has a code (such as invalid_type, too_small, too_big, invalid_value or unrecognized_keys), a path and a message, plus fields specific to the code, such as minimum or the allowed values. To map issues to your own form fields, join path with dots.

A 400 for a business rule, such as an unknown column name in the usage export, has no issues and zodError is null; the message explains the problem.

Reason tokens

Some refusals carry a data.reason token so your code can react without parsing the message. Tokens are lowercase snake_case identifiers that stay the same when the wording of message changes. New tokens can be added, so treat an unknown token like a refusal without a reason.

Unexpected errors

When something fails inside Vetnio, the response is 500 with the message An unexpected error occurred. The real cause is logged on Vetnio's side and is never sent to you, and stack traces are never included.

A few limits are currently reported this way instead of with a 4xx code, for example a record longer than 50,000 characters or a clinic that already has the maximum number of templates. If a 500 repeats for the same input, check Limits before you retry. Such errors may get a more specific status code in the future, so handle errors by status class rather than by exact code.

When you contact Vetnio support about an error, include the time of the request, the method and path, and the x-vercel-id header from the response. Never include your API key.

Retrying safely

Retry only when the error is temporary and the request is safe to repeat.

A request that timed out may still have succeeded on Vetnio's side. Before repeating a request that creates something, check whether the first attempt went through.

Next steps

• Limits: rate limits, timeouts and size limits behind 429, 413, 504 and some 500 errors.
• Pagination: how to page through lists without missing or repeating items.
• Authentication: the key types behind 401 and 403.