Errors

Every Clement error response uses the same envelope. Each carries a machine-readable code and a doc_url pointing back here.

Envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Required field 'subject' is missing.",
    "param": "subject",
    "request_id": "req_01HZ8X3J9K7P2QV6R5N4M3T2L1",
    "doc_url": "https://clement.so/docs/errors/missing_parameter"
  }
}

type is one of a small enum that maps cleanly to HTTP status families. code is the precise, stable identifier — branch on this, not message. request_id matches the X-Request-Id header on every response (errored or not) and is the one thing to quote when opening a support ticket.

Codes

400 Invalid request

• invalid_request — The request was rejected before validation — usually a missing or malformed field.
• idempotency_key_required — A side-effect-bearing POST was missing the `Idempotency-Key` header.
• confirmation_required — A high-blast-radius destructive op was called without `?confirm=true`.
• invalid_email — An email address didn't pass syntactic validation.
• invalid_contact_id — An ID in `contact_ids` didn't decode as a contact ID.
• duplicate_in_batch — A batch payload contained duplicate entries (same email or same ID).
• missing_email_column — A CSV import didn't map any column to `email`.
• too_many_rows — A bulk endpoint received more rows than its per-call cap.

401 Authentication

• unauthenticated — No valid bearer key or session cookie was found on the request.

403 Authorization

• forbidden — The key authenticated, but its scope tier doesn't permit this action.
• subscription_required — The workspace has no active plan.

404 Not found

• resource_not_found — The resource doesn't exist or isn't visible to this workspace.

409 Conflict

• api_key_revoked — The presented key was valid once, but has been revoked.
• idempotency_key_in_use — The `Idempotency-Key` was reused with a different request body.
• idempotency_request_in_progress — Another request with this `Idempotency-Key` is still running.
• idempotency_replay_unavailable — The request already succeeded, but its response held a one-time secret.
• invalid_state_transition — The resource is in a state that doesn't permit the requested transition.
• inbox_provider_conflict — The address is already connected through another provider.

422 Unprocessable

• validation_failed — The body parsed as JSON but failed Zod schema validation.
• inbox_connection_failed — Clement couldn't log in to the SMTP or IMAP server you supplied.

429 Rate limit

• rate_limit_exceeded_key — This API key exceeded its sustained or burst request rate.
• rate_limit_exceeded_workspace — The workspace exceeded its aggregate request rate across all keys.
• quota_exceeded — The workspace hit a plan-level quota (sends, contacts, webhooks).

500 Server error

• internal_error — An unexpected error escaped a route handler.