How to handle API errors

Before you start

The UrbanFox API returns structured errors following the RFC 7807 standard. This guide shows you how to parse these responses and take the correct action for each error type.

An authenticated integration making requests to the UrbanFox API

Check the error shape

Every error response follows RFC 7807 Problem Details:

{
  "title": "Application Error",
  "status": 404,
  "type": "item-not-found",
  "detail": "Case not found",
  "errors": null
}

Parse the response

Use the same flow in any HTTP client:

Check the HTTP status code.
For 4xx or 5xx responses, parse the JSON response body.
Use the type field for programmatic handling.
Use the detail and errors fields for logs, support messages, or user-facing validation feedback.

Handle by status code

Use the status code and type field for the first routing decision:

Status	Type	Action
`400`	`bad-request`	Malformed request; check the body and parameters
`401`	`unauthorized`	Token is invalid or expired; re-authenticate
`403`	`access-denied`	Missing permission or tenant mismatch; check credentials
`404`	`item-not-found`	The resource does not exist; verify the ID
`409`	`item-already-exists`	Resource already exists; use a different ID or fetch the existing one
`422`	`validation-error`	Request body failed schema validation; see field errors
`500`	`internal-error`	Retry with exponential backoff; report if persistent
`502`	`bad-gateway`	Upstream dependency failed; retry after a short delay

Handle validation errors

For 422 responses, the errors array contains one entry per invalid field:

{
  "title": "Validation Error",
  "status": 422,
  "type": "validation-error",
  "detail": "Request validation failed",
  "errors": [{ "field": "email", "message": "Invalid email format" }]
}

Iterate over errors[] to surface field-specific messages to users or logs. For other error types, use detail as the operational message.

If it's not working

Symptom	Action
Response body is not JSON	Check you are calling the correct base URL
`errors` array is null on a 400	Not all 400 responses are validation errors; use `type` to distinguish