Reference
Protocol Spec
Full Surf protocol specification and error codes
Protocol Spec#
The full Surf protocol specification is available on GitHub:
Server Error Codes (SurfErrorCode)
| Code | HTTP | Meaning |
|------|------|---------|
| UNKNOWN_COMMAND | 404 | Command not found in manifest |
| NOT_FOUND | 404 | Domain resource not found |
| INVALID_PARAMS | 400 | Missing required param or wrong type |
| AUTH_REQUIRED | 401 | Command requires auth but none provided |
| AUTH_FAILED | 403 | Token is invalid or expired |
| SESSION_EXPIRED | 410 | Session ID no longer valid |
| RATE_LIMITED | 429 | Too many requests (check Retry-After) |
| INTERNAL_ERROR | 500 | Unexpected server error |
| NOT_SUPPORTED | 501 | Feature not available |
Client Error Codes (SurfClientErrorCode)
These are thrown by @surfjs/client for transport-level failures:
| Code | Meaning |
|------|---------|
| NETWORK_ERROR | Network-level failure (WebSocket closed, fetch failed) |
| TIMEOUT | Request or discovery timed out |
| NOT_CONNECTED | Transport not connected — call connect() first |
| INVALID_MANIFEST | Manifest response was invalid or missing required fields |
| MAX_RETRIES | All retry attempts exhausted |
| HTTP_ERROR | Non-OK HTTP response from a raw HTTP request |