---
title: Errors
description: The error envelope and every error code the API can return, grouped by HTTP status.
canonical_url: https://wiblo.app/docs/developers/api/errors
last_updated: 2026-07-28T17:12:38+02:00
md_url: https://wiblo.app/docs/developers/api/errors.md
---

# Errors

Every non-2xx response uses one envelope:

```json
{
  "error": {
    "code": "BOOKING_CONFLICT",
    "message": "Human-readable explanation.",
    "request_id": "req_01J...",
    "details": { }
  }
}
```

`code` is stable and machine-readable — switch on it, never on `message`. `request_id` is a server-minted ULID that also rides the `X-Request-Id` response header; include it when reporting a problem. `details` carries structured context on validation and conflict errors and is stripped from `500` responses.

## 400 Bad request

- `ACCESS_DENIED`
- `AUTHORIZATION_PENDING`
- `BAD_REQUEST`
- `EXPIRED_TOKEN`
- `FILE_NOT_TEXT`
- `INVALID_CLIENT`
- `INVALID_FILE_PATH`
- `INVALID_REPO_FOLDER`
- `SLOW_DOWN`
- `VALIDATION_FAILED`

## 401 Unauthorized

- `INVALID_TOKEN`
- `UNAUTHENTICATED`

## 403 Forbidden

- `ADMIN_REQUIRED`
- `BOOKING_FORBIDDEN`
- `INSUFFICIENT_PRIVILEGE`
- `OWNER_REQUIRED`
- `SELF_EDIT_ONLY`

## 404 Not found

- `AGENT_RUN_NOT_FOUND`
- `AGENT_THREAD_NOT_FOUND`
- `AGENT_USER_INPUT_NOT_FOUND`
- `API_KEY_NOT_FOUND`
- `AVAILABILITY_NOT_FOUND`
- `BOOKING_NOT_FOUND`
- `CLI_TOKEN_NOT_FOUND`
- `DEVICE_CODE_NOT_FOUND`
- `FILE_NOT_FOUND`
- `HOST_NOT_FOUND`
- `INVITE_NOT_FOUND`
- `MACHINE_MEMBER_NOT_FOUND`
- `MEMBER_NOT_FOUND`
- `NOT_FOUND`
- `OUT_OF_OFFICE_NOT_FOUND`
- `REPO_FOLDER_NOT_FOUND`
- `REPO_NOT_FOUND`
- `REQUIREMENT_NOT_FOUND`
- `RESOURCE_NOT_FOUND`
- `SCHEDULE_NOT_FOUND`
- `SEAT_NOT_FOUND`
- `SERVICE_NOT_FOUND`
- `TAG_NOT_FOUND`
- `WORKSPACE_NOT_FOUND`

## 405 Method not allowed

- `METHOD_NOT_ALLOWED`

## 409 Conflict

- `AGENT_RUN_ENDED`
- `AGENT_SANDBOX_UNAVAILABLE`
- `AGENT_USER_INPUT_ALREADY_RESOLVED`
- `ALREADY_MEMBER`
- `BOOKING_CONFLICT`
- `BOOKING_LIMIT_REACHED`
- `BOOKING_SEATS_FULL`
- `DEVICE_CODE_USED`
- `HOST_ALREADY_ASSIGNED`
- `INVITE_ALREADY_USED`
- `LAST_OWNER`
- `MACHINE_MEMBER_NAME_TAKEN`
- `MEMBER_ALREADY_LINKED`
- `MEMBER_NOT_INVITABLE`
- `OUTSIDE_WORKING_HOURS`
- `OVERLAPPING_OOO`
- `REPO_FOLDER_EXISTS`
- `REPO_NAME_TAKEN`
- `REQUIREMENT_ALREADY_EXISTS`
- `RESOURCE_IN_USE`
- `SCHEDULE_ALREADY_EXISTS`
- `SLUG_TAKEN`
- `TAG_NAME_TAKEN`
- `TURN_ALREADY_ACTIVE`
- `WORKSPACE_ARCHIVED`
- `WORKSPACE_LIMIT_REACHED`

## 410 Gone

- `DEVICE_CODE_EXPIRED`
- `INVITE_EXPIRED`

## 413 Payload too large

- `FILE_TOO_LARGE`

## 422 Unprocessable entity

- `AGENT_LOCAL_TARGET_UNSUPPORTED`
- `AGENT_RUN_NOT_GIT_BACKED`
- `AGENT_SOURCE_REPO_NOT_FOUND`
- `CONFIRM_MISMATCH`
- `COUNTRY_NOT_SUPPORTED`
- `HOLIDAY_COUNTRY_NOT_SET`
- `HOST_MUST_BE_HUMAN`
- `INVALID_EMAIL`
- `INVALID_HOLIDAY_EVENT`
- `INVALID_PARAMS`
- `INVALID_PERIOD`
- `INVALID_SLUG`
- `INVALID_TTL`
- `KEY_NOT_LIVE`
- `MEMBER_MUST_BE_HUMAN`
- `NOT_DATE_OVERRIDE`
- `OVERLAPPING_BLOCKS`
- `REQUIREMENT_QUANTITY_INVALID`
- `REQUIREMENT_TARGET_INVALID`
- `RESTRICTION_OUTSIDE_BASELINE`
- `ROLE_CAP_EXCEEDED`
- `SCHEDULE_OWNER_INVALID`
- `SEATED_NOT_RECURRING`
- `SERVICE_HAS_NO_HOSTS`

## 429 Too many requests

- `RATE_LIMITED`

## 500 Internal server error

- `INTERNAL`

## 502 Bad gateway

- `REPO_CLONE_FAILED`
- `UPSTREAM_UNAVAILABLE`

Rate-limited routes also return `Retry-After`, and every response from them carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.