Error Reference

Complete reference for errors returned by the NoLag REST API and WebSocket connections.

REST API Errors

Error Format

All REST API error responses return a JSON object with three fields:

{
  "id": "uuid",
  "message": "Human-readable error description",
  "timestamp": "2024-01-15T12:00:00Z"
}
FieldTypeDescription
idstring (UUID)Unique identifier for this error instance. Include this when contacting support.
messagestringHuman-readable description of what went wrong.
timestampstring (ISO 8601)When the error occurred.

HTTP Status Codes

StatusNameWhen
400Bad RequestValidation failed, invalid UUID, malformed request body
401UnauthorizedMissing or invalid API key/token
403ForbiddenValid credentials but insufficient permissions
404Not FoundResource does not exist or has been deleted
409ConflictDuplicate resource (e.g. unique constraint violation)
502Bad GatewayUpstream service unavailable

Response Examples

400 Bad Request

Returned when the request fails validation or contains malformed data.

{
  "id": "01939f83-8b57-7c3e-a456-426614174001",
  "message": "Invalid appId UUID format",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

401 Unauthorized

Returned when the API key is missing, malformed, or no longer valid.

{
  "id": "01939f83-8b57-7c3e-a456-426614174002",
  "message": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

403 Forbidden

Returned when the credentials are valid but lack permission to access the resource.

{
  "id": "01939f83-8b57-7c3e-a456-426614174003",
  "message": "API key must be project-scoped to access this endpoint",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

404 Not Found

Returned when the requested resource does not exist or has been deleted.

{
  "id": "01939f83-8b57-7c3e-a456-426614174004",
  "message": "App not found",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

409 Conflict

Returned when a create or update would violate a uniqueness constraint.

{
  "id": "01939f83-8b57-7c3e-a456-426614174005",
  "message": "A room with this slug already exists",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

502 Bad Gateway

Returned when an upstream service is unreachable or returned an unexpected response.

{
  "id": "01939f83-8b57-7c3e-a456-426614174006",
  "message": "Upstream service unavailable",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

WebSocket Errors

Error Format

WebSocket errors are delivered as JSON messages on the open connection:

{
  "type": "error",
  "error": "error_name",
  "code": 42910,
  "topic": "app/room/topic"
}
FieldTypeDescription
typestringAlways "error".
errorstringMachine-readable error name.
codenumberNumeric error code. Only present for rate, quota, and size errors.
topicstringOptional. Included when the error relates to a specific topic.

Error Codes

CodeErrorDescription
42910rate_limit_exceededMore than 50 messages/second on this connection.
42920monthly_quota_exceededProject has exceeded its monthly message quota.
42930message_too_largePayload exceeds the plan limit. The response includes maxSizeBytes.
-not_authorizedACL denied access to the topic or lobby.
-not_subscribedAttempted a filter update on a topic not subscribed to.
-invalid_filter_charsFilter contains /, #, or + characters.
-too_many_filtersMore than 100 filters specified for a topic.
-not_authenticatedMessage sent before authentication completed.

Close Codes

The server may close the WebSocket connection with a specific close code:

CodeReasonDescription
4002connection_limit_reachedOrganization has hit its concurrent connection limit.

Server-Initiated Disconnect

Before closing the connection, the server sends a disconnect message. This occurs when a token is revoked or revalidation fails.

{
  "type": "disconnect",
  "reason": "token_invalid"
}

Authentication Errors

If authentication fails, the server responds with an auth message indicating the failure:

{
  "type": "auth",
  "success": false,
  "error": "invalid_token"
}

Possible error values:

  • "invalid_token"
  • "connection_limit_reached"
  • "broker_unavailable"

Next Steps