Errors

Every error response is JSON with a stable, machine-readable code you can branch on, plus a human-readable message and optional details.

The error envelope

{
  "code": "invalid_request",
  "message": "The request payload is invalid.",
  "details": [
    { "path": ["slideCount"], "message": "Number must be greater than or equal to 3" }
  ]
}

• code — stable identifier. Switch on this, not on message.
• message — human-readable; may change over time.
• details — present on validation errors; mirrors the failing fields.

Tip

The details array on invalid_request comes straight from request-body validation, so it points at the exact field and constraint that failed.

Common codes

HTTP	code	Meaning
401	missing_api_key	No Authorization: Bearer header was sent.
401	invalid_api_key	The key is unknown, malformed, or revoked.
400	invalid_json	The request body was not valid JSON.
400	invalid_request	The body failed validation — see details.
400	invalid_media_file	The file field was missing on an upload.
400	unsupported_media_type	The upload was not an image or video.
404	platform_not_found	The platform is missing, disabled, or needs refresh.
409	post_limit_reached	The plan’s monthly post quota is exhausted.

Endpoint-specific codes (for example around credits or media readiness) are described on the relevant API Reference pages.

Handling errors well

• Treat 4xx as terminal unless the code clearly indicates a transient condition. Don’t blindly retry a 400/401/409.
• Surface the code, not just the message, in logs and alerts — it’s stable.
• For uploads, confirm the returned object’s status is READY before referencing its id in a post.

CLI errors

The CLI wraps the same failures. It prints a structured error to stderr and exits non-zero, so scripts and agents can branch without scraping prose:

{ "error": { "code": "not_authenticated", "message": "No API key found. Run `loomta auth:login`…" } }