Errors

Errors use standard HTTP status codes and a JSON body with a human-readable detail and a machine-readable code. Match on code in your integration, since detail can change wording.

Error format

Errors that aren't about a single field:

{ "detail": "Invalid API key.", "code": "authentication_failed" }

Validation errors have one entry per field that failed:

{
  "country": { "detail": "\"Sweden\" is not a valid choice.", "code": "invalid_choice" },
  "portfolio_id": { "detail": "Invalid pk \"...\" - object does not exist.", "code": "does_not_exist" }
}

A field with several problems has a list of { "detail", "code" } objects instead of a single one.

Status codes

Status	Code	When
400 Bad Request	per field	A filter value or request field is invalid.
401 Unauthorized	authentication_failed	The API key is missing, wrong, rotated or revoked, or its user is deactivated.
403 Forbidden	external_api_create_not_allowed	You tried to create a property, but creating isn't enabled for your organization.
404 Not Found	not_found	No portfolio or property with this ID in your organization.
405 Method Not Allowed	method_not_allowed	The endpoint doesn't support this method, such as DELETE.
500 Internal Server Error		Something went wrong on Telescope's side. Telescope is notified automatically. Retry later.

A 404 doesn't tell you whether the ID exists in another organization. To your key, other organizations' data doesn't exist.

Common validation errors

Filters on the property list:

{ "hazard": { "detail": "Select a valid choice. flood is not one of the available choices.", "code": "invalid_choice" } }

Filter values are case-sensitive and must not have spaces after the commas. See allowed values.

Creating a property: see the error table in Create properties.

Retrying

• Retry 500 and network errors with a growing delay.
• Don't retry 400, 401, 403 or 404 unchanged. Fix the request or the key first.
• When retrying a create, send an internal_reference_id, so a request that succeeded before the connection dropped updates the property instead of creating a second one.