Error codes & troubleshooting

Error Response Format

{
  "status": "error",
  "error": {
    "code": "NO_AVAILABILITY",
    "message": "No available time slots found for the requested date",
    "details": {
      "requested_date": "2026-03-15",
      "next_available": "2026-03-17"
    }
  }
}

Error Codes

Code	HTTP Status	Description	Resolution
AUTH_FAILED	401	Invalid or missing auth credentials	Check API key/signature settings
CLIENT_NOT_FOUND	404	Webhook config does not map to an active client	Verify endpoint and provider mapping
NO_AVAILABILITY	422	No available slots for requested date	Expand FSM availability or select another date
FSM_DISCONNECTED	503	FSM connection is unavailable	Reconnect the FSM integration
FSM_ERROR	502	Upstream FSM returned an error	Check FSM account status and retry
INVALID_PAYLOAD	400	Missing/invalid required fields	Validate against payload reference
RATE_LIMITED	429	Request rate exceeded	Retry with exponential backoff
DUPLICATE_REQUEST	409	Duplicate request already processed	Reuse original result; no further action

Troubleshooting Checklist

• 401 responses: verify API key and signature headers
• 422 availability issues: confirm FSM timezone and technician schedules
• 202 but no job created yet: check dispatch processing status and integration health
• Duplicate dispatches: include a stable call ID in each webhook request