Error Reference

How the NoLag REST API communicates errors and how to handle them.

Error Format

All error responses return a JSON object with three fields:

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

Field	Type	Description
`id`	string (UUID)	Unique identifier for this error instance. Use 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	Meaning	Common Causes
`400`	Bad Request	Invalid UUID format, missing required fields, validation failure
`401`	Unauthorized	Missing or invalid API key, expired token
`403`	Forbidden	API key is not project-scoped, resource belongs to a different project
`404`	Not Found	Resource does not exist or has been deleted
`409`	Conflict	Duplicate resource (e.g., room slug already exists within the app)

Examples

400 Bad Request

Returned when the request is malformed or fails validation.

// 400 Bad Request — validation failure
{
  "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.

// 401 Unauthorized — missing or invalid API key
{
  "id": "01939f83-8b57-7c3e-a456-426614174004",
  "message": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

403 Forbidden

Returned when the API key does not have permission to access the resource. All endpoints require a project-scoped API key.

// 403 Forbidden — API key lacks access
{
  "id": "01939f83-8b57-7c3e-a456-426614174005",
  "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, has been soft-deleted, or does not belong to the project associated with your API key.

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

409 Conflict

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

// 409 Conflict — duplicate resource
{
  "id": "01939f83-8b57-7c3e-a456-426614174003",
  "message": "A room with this slug already exists",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Handling Errors

Always check the HTTP status code first to determine the category of error.
Use the message field for debugging and user-facing feedback.
Save the id field when reporting issues to NoLag support for faster resolution.
For 401 errors, verify your API key is correct and has not been revoked.
For 404 errors, confirm the resource ID is correct and the resource belongs to the project associated with your API key.