Errors and Troubleshooting

Understand Vision API v3 responses, recover from errors, and retry requests without creating duplicate inspections.

Handle Vision API v3 errors, choose when to retry, and avoid creating duplicate inspections.

Response envelope

Every Vision API v3 response, whether successful or an error, is JSON with a response envelope (the fields surrounding the response data).

FieldTypeWhen presentHow to use it
response_codeIntegerEvery responseThe HTTP status code, repeated in the body. Use it to identify success or the type of failure.
messageStringEvery responseHuman-readable display text. It can be reworded at any time. Never branch on it.
api_versionStringEvery responseThe API version that served your request.
error_codeStringSome 4xx errorsA stable, machine-readable reason for the error. Branch on this, not on message.
resultVaries by endpointSuccessful responsesThe data returned by the endpoint.

Success response

A successful create-inspection response includes the inspection in result. This abbreviated example shows selected inspection fields:

{
  "response_code": 200,
  "message": "Success",
  "api_version": "3.0.0",
  "result": {
    "id": 789,
    "team_id": 123,
    "inspection_type_id": 456
  }
}

Error response

A 400 response can include an error_code that your integration uses to offer a specific recovery action. This illustrative example shows a phone number that cannot receive SMS; the message text can change:

{
  "response_code": 400,
  "message": "The phone number cannot receive text messages.",
  "api_version": "3.0.0",
  "error_code": "phone_cannot_receive_text"
}

For this error, ask the customer for a mobile number or send the inspection by email instead. If error_code is absent, handle the response using its HTTP status code.

Status codes and what to do

Status codeWhat it meansWhat to do
400Your request is invalid or not allowed in the inspection's current state.Read message for context and fix the request. Do not retry it unchanged. Use a recognized error_code for specific recovery logic.
401Your token is missing, invalid, or expired.Request a new token and retry once.
403Your credentials are valid but do not have access to that team or resource.Confirm that your credentials have access to the requested team or resource before trying again.
404The resource was not found. The message is always "Not Found", whatever the cause. This includes resources on a team your credentials cannot see.Check the resource ID and your credentials' team access. The message does not distinguish between a missing resource and one you cannot access.
429Your integration exceeded the rate limit.Back off and retry. See Rate limits on API Overview.
5xxA Vision error occurred. The message is always "An error occurred".Retry with exponential backoff (increase the delay between attempts). If the error persists, contact support with the time and endpoint. For create requests, follow the duplicate-prevention guidance below before retrying.

Error codes

Use these stable error_code values to choose a specific recovery action:

error_codeWhen you receive itWhat to do
phone_cannot_receive_textYou create an inspection with a text send method, but the phone number cannot receive SMS. The number may be a landline, invalid, or not found.Ask the customer for a mobile number or send the inspection by email instead.
website_form_outdatedWebsite Forms only: the form changed since the customer loaded it.Reload the form and resubmit.

Other codes exist for dashboard-only features. Treat any unknown error_code like a regular 4xx response: follow the status-code guidance and display message for context without branching on its text.

Retries and duplicates

POST /v3/inspections has no idempotency key (a value that prevents repeated requests from creating the same resource more than once). If a create request times out, you do not know whether Vision created the inspection. Do not retry blindly: you can create duplicate inspections and send the customer two messages.

Before creating again:

  1. Search for the inspection with GET /v3/inspections, for example by your reference ID or customer details. See Find Inspections for search and filtering guidance.
  2. If you find the inspection, use that existing inspection instead of creating another one.
  3. If you confirm that the inspection was not created, send the create request again.

Apply this duplicate check whenever you cannot tell whether a create request succeeded, rather than treating backoff alone as protection against duplicates.


Did this page help you?