Errors

All errors share a consistent shape:

{
  "error": { "code": "not_found", "message": "Video not found" },
  "meta": { "request_id": "req_xxxxx" }
}

The error.code is a stable machine-readable string. The error.message is human-readable and may change between versions. Parse code, log message.

Error codes

Code	HTTP	When it fires	Recommended client action
`unauthorized`	401	Missing, malformed, or invalid `Authorization` header	Check the header is `Bearer lymo_...`; re-issue the key if it’s been revoked
`invalid_key_metadata`	401	Key signature is valid but Lymo-specific metadata is missing	Re-issue the key from the web app — it was created outside the normal flow
`forbidden`	403	Key lacks the required scope, or the organization is inactive	Check your key’s scopes; contact support if the org should be active
`not_found`	404	Resource doesn’t exist, or it exists in a different organization	See cross-tenant 404 below
`bad_request`	400	Malformed header — e.g. `Idempotency-Key` longer than 256 characters	Fix the header and retry
`validation_failed`	422	Query parameters or request body failed schema validation	Read `message` for the failing field path; fix and retry
`invalid_webhook_url`	422	`POST /v1/webhooks` destination URL isn’t on your org’s hostname allowlist	See Webhooks → Hostname allowlist
`rate_limited`	429	Too many requests for this key (when enforcement is configured — see below)	Honor the `Retry-After` header (seconds); back off exponentially thereafter
`service_unavailable`	503	Key-verification service is temporarily unavailable	Retry with backoff; escalate if it persists more than a minute
`internal_error`	500	Unexpected server error	Retry once; if it persists, report the `request_id`

Cross-tenant 404

Resources that belong to a different organization return 404 not_found, not 403 forbidden. This is intentional — 403 would leak the fact that an ID exists; 404 is indistinguishable from “never existed.” This applies to every resource path, not just videos. Concretely: if your key is for org A, calling GET /v1/videos/{id} with a video ID from org B returns:

{
  "error": { "code": "not_found", "message": "Video not found" },
  "meta": { "request_id": "req_xxxxx" }
}

If a resource you know exists returns 404, the most common cause is that the API key is scoped to a different organization than you expected. Check it with:

curl "$LYMO_BASE/v1/members/me" -H "Authorization: Bearer $LYMO_KEY"

The returned member’s organization is the only one this key can see.

Key self-revocation

If a key is compromised, the holder can revoke it without web UI access:

curl -X DELETE "$LYMO_BASE/v1/keys/me" -H "Authorization: Bearer $LYMO_KEY"
# → { "data": { "revoked": true }, "meta": {...} }

This endpoint requires no permission scope — any key can always revoke itself. After revocation, every subsequent request with the same key returns 401 unauthorized.

Using `request_id`

Every response — success or error — includes meta.request_id. When reporting issues, include it: we can trace the exact request server-side, including timing, inputs, and which backend service handled it.

{
  "error": { "code": "internal_error", "message": "An unexpected error occurred" },
  "meta": { "request_id": "req_fa29e58a3cfb4c0fbab0a75f82c4c7a3" }
}

Format is req_ followed by 32 lowercase hex characters (a UUID with dashes removed). The same ID is echoed on the X-Request-Id response header so you can grep logs end-to-end.

Rate limits

Rate-limit enforcement is per-API-key. When a limit is exceeded the response is 429 rate_limited with a Retry-After header specifying seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded" }, "meta": {...} }

Rate limits are not yet enforced on all issued keys. Future versions will apply sensible defaults per scope. Design clients to always honor Retry-After rather than hard-coding intervals, so the switch to enforcement is a no-op for you.

Validation errors

validation_failed (422) is the most common error during development. The message field names the offending field path:

{
  "error": {
    "code": "validation_failed",
    "message": "limit: Number must be less than or equal to 100"
  },
  "meta": { "request_id": "req_..." }
}

Common causes:

limit outside 1–100 (default is 25)
created_after / created_before not a valid ISO 8601 timestamp
status filter not in the allowed enum — see the API Reference tab for per-resource status values
Missing required body field on POST /v1/webhooks

Get started

Concepts

Error codes

Cross-tenant 404

Key self-revocation

Using `request_id`

Rate limits

Validation errors

​Error codes

​Cross-tenant 404

​Key self-revocation

​Using request_id

​Rate limits

​Validation errors

Error codes

Cross-tenant 404

Key self-revocation

Using `request_id`

Rate limits

Validation errors