---
title: Error Reference
description: Complete reference for NoLag REST API and WebSocket errors, status codes, and error handling.
---

# 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:

```json [JSON]
{
  "id": "uuid",
  "message": "Human-readable error description",
  "timestamp": "2024-01-15T12:00:00Z"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (UUID) | Unique identifier for this error instance. Include this when contacting support. |
| `message` | string | Human-readable description of what went wrong. |
| `timestamp` | string (ISO 8601) | When the error occurred. |

### HTTP Status Codes

| Status | Name | When |
| --- | --- | --- |
| `400` | Bad Request | Validation failed, invalid UUID, malformed request body |
| `401` | Unauthorized | Missing or invalid API key/token |
| `403` | Forbidden | Valid credentials but insufficient permissions |
| `404` | Not Found | Resource does not exist or has been deleted |
| `409` | Conflict | Duplicate resource (e.g. unique constraint violation) |
| `502` | Bad Gateway | Upstream service unavailable |

### Response Examples

#### 400 Bad Request

Returned when the request fails validation or contains malformed data.

```json [JSON]
{
  "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.

```json [JSON]
{
  "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.

```json [JSON]
{
  "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.

```json [JSON]
{
  "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.

```json [JSON]
{
  "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.

```json [JSON]
{
  "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:

```json [JSON]
{
  "type": "error",
  "error": "error_name",
  "code": 42910,
  "topic": "app/room/topic"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Always `"error"`. |
| `error` | string | Machine-readable error name. |
| `code` | number | Numeric error code. Only present for rate, quota, and size errors. |
| `topic` | string | Optional. Included when the error relates to a specific topic. |

### Error Codes

| Code | Error | Description |
| --- | --- | --- |
| `42910` | `rate_limit_exceeded` | More than 50 messages/second on this connection. |
| `42920` | `monthly_quota_exceeded` | Project has exceeded its monthly message quota. |
| `42930` | `message_too_large` | Payload exceeds the plan limit. The response includes `maxSizeBytes`. |
| - | `not_authorized` | ACL denied access to the topic or lobby. |
| - | `not_subscribed` | Attempted a filter update on a topic not subscribed to. |
| - | `invalid_filter_chars` | Filter contains `/`, `#`, or `+` characters. |
| - | `too_many_filters` | More than 100 filters specified for a topic. |
| - | `not_authenticated` | Message sent before authentication completed. |

### Close Codes

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

| Code | Reason | Description |
| --- | --- | --- |
| `4002` | `connection_limit_reached` | Organization 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.

```json [JSON]
{
  "type": "disconnect",
  "reason": "token_invalid"
}
```

### Authentication Errors

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

```json [JSON]
{
  "type": "auth",
  "success": false,
  "error": "invalid_token"
}
```

Possible `error` values:

- `"invalid_token"`
- `"connection_limit_reached"`
- `"broker_unavailable"`

## Next Steps

- [REST API Reference](/docs/api-reference)
- [WebSocket API Reference](/docs/api-reference/websocket)
- [Wire Protocol](/docs/protocol)