Errors

Two kinds of error

Errors raised by the gateway (bad credentials, rate limits, an API being unreachable…) are RFC 9457 problem documents with Content-Type: application/problem+json:

{
  "type": "https://api2.evercam.io/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired credentials.",
  "api": "labs",
  "request_id": "8f2c1d0e6b7a4c39a1e2f3b4c5d6e7f8"
}

type identifies the error and links to its section below. api names the API the request was for, and request_id matches the X-Request-Id response header.

Errors raised by an API are passed through untouched, in that API's own format. Those formats vary:

API	Error body
Dash, Admin	`{"code", "message", "details", "inner_error"}`
AI	`{"success": false, "message", "errors": [...]}`
360, BIM, Drone	`{"detail": ...}`
Labs	`{"message", "details"}` (some routes answer plain text)
Workflows	its own envelope (see its reference)

To tell them apart, check the content type: only the gateway sends application/problem+json.

Request IDs

Every response carries X-Request-Id. Send your own (up to 128 characters of A-Z a-z 0-9 . _ -) to correlate requests with your logs; otherwise the gateway generates one. It's forwarded to the API, so include it when reporting a problem.

Gateway error types

unauthorized

401. Credentials are missing, invalid or expired, or use an unsupported Authorization scheme. The response includes WWW-Authenticate: Bearer. See authentication.

api-key-not-supported

401. An API key pair (X-API-ID/X-API-KEY) was sent to an API that only accepts access tokens. Only Dash and Admin take key pairs.

forbidden

403. Valid credentials, not allowed. The Admin API requires an Evercam administrator account.

rate-limited

429. Too many requests. Wait Retry-After seconds. See rate limits.

identity-unavailable

503. The gateway couldn't verify your credentials right now. Retry after the Retry-After delay.

not-found

404. Unknown API (the first path segment isn't one of the APIs in /apis.json), or a path that isn't available through the gateway.

bad-request

400. The request is malformed: for example, a path containing .. or // segments, or an invalid Content-Length.

method-not-allowed

405. The HTTP method isn't supported for one of the gateway's own endpoints.

payload-too-large

413. The request body exceeds the API's size limit (10–50 MB depending on the API). Large files (360 walks, drone flights, BIM models) are uploaded to the upload server first, and their URLs are then sent to the API.

upstream-unavailable

502. The API couldn't be reached. Retry with backoff; check status.

upstream-timeout

504. The API didn't answer in time. Most endpoints have 60 seconds; exports and other long-running operations have up to 15 minutes.

internal-error

500. An unexpected error in the gateway. Please report it with the request_id.