Skip to content
Transpira

Error handling

Response format

API error responses have a Content-Type: application/json header, and their body shape follows the RFC 7807 problem details format: type, title, status, and detail fields. Input validation errors additionally include an errors field — a dictionary of field names mapped to a list of messages for each.

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "email": ["email must be a valid email address"]
    }
}

Status codes

  • 400 Bad Request — invalid input (a validation error); the response body includes details in the errors field.
  • 401 Unauthorized — the token is missing, invalid, or expired. The response to missing/invalid credentials may not include a JSON body — check the status code first.
  • 403 Forbidden — the token is valid, but the account doesn't have permission for the requested operation or resource (for example its role or site scope doesn't allow it).
  • 404 Not Found — the requested resource doesn't exist, or doesn't belong to the specified organization.
  • 429 Too Many Requests — the rate limit was exceeded — see the rate limits page.

Recommendations

Treat the HTTP status code as the primary source of truth for the error type, and the title / detail / errors fields as an additional, human-readable description.