Error Format

All Integrations API errors follow RFC 7807 Problem Details. Responses have the application/problem+json content type and a predictable shape:

{
  "type": "https://backroadstatus.com/developer/docs/errors#bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "Report date cannot be in the future."
}

Field	Description
type	A URL fragment identifying the error class. Anchors into this page.
title	Short human-readable title.
status	HTTP status code.
detail	Human-readable explanation of what went wrong.
errors	Present on validation failures. Array of { field, message }.

Error types

#bad-request

HTTP 400. A parameter or value was unacceptable. The detail field explains what.

#malformed-request

HTTP 400. The request body could not be parsed as JSON.

#validation-failed

HTTP 400. One or more fields failed bean validation. Inspect the errors array.

{
  "type": "https://backroadstatus.com/developer/docs/errors#validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "errors": [
    { "field": "pathId", "message": "must not be blank" }
  ]
}

#forbidden

HTTP 403. The access token is missing a required scope, or the user does not have permission to act on the resource.

#not-found

HTTP 404. The requested resource does not exist, or you cannot see it.

#internal-error

HTTP 500. Something went wrong on our end. Retry with exponential backoff.

Handling errors

Clients should branch on status first and inspect type only when they need to distinguish between multiple errors that share a status code (for example, bad-request vs. validation-failed).