Handle API errors, booking conflicts, and uncertain write outcomes.

Errors and retries

The REST routes return JSON errors with an error string. The error text is human readable, and its values vary by endpoint. Do not build recovery logic that depends on an exact sentence. Some invite errors use machine-readable strings in error; the API has no single standardized error code field.

json

{
  "error": "API key is missing the required scope: interviews:write"
}

Errors

Status	Meaning	Action
`400`	Invalid input or unsupported operation.	Correct the request before retrying. Confirm the round is a bookable live assessment.
`401`	Authentication failed.	Check your Bearer header, key, and organization access.
`403`	The key lacks a required permission.	Add the scope named in the response.
`404`	A resource is missing or outside your organization.	Verify the ID and key's organization.
`409`	A booking, candidate, or availability conflict.	Read the error and reconcile the existing state before making another write.
`500`	An unexpected server error.	Retry reads with backoff. For a booking request, check whether it succeeded before retrying.
`502`	A previous session's notetaker could not be dismissed during rebooking.	Check the existing interview before trying again.

A booking can return 409 when the candidate already has an interview, the slot is full, the interviewer is already booked at that start time, or the candidate belongs to a different posting, track, or assessment. Candidates who have submitted, expired, or otherwise left an active assessment state cannot be booked without resolving that state first.

Retry booking requests safely

The API does not currently support idempotency keys. If POST /interviews times out or returns an unexpected error:

Query GET /interviews with posting_id, round_id, and candidate_email.
Compare the result with your intended booking and save its ID if it succeeded.
Retry only after determining that the intended booking does not exist.

Leave replace_existing unset for initial bookings. A duplicate request then returns 409 instead of replacing the candidate's existing interview. Use replace_existing: true only for an intentional reschedule; repeating it can reset the session and send booking emails again.

A 201 response with warnings is a successful booking that needs follow-up. Do not retry it to resolve a warning. For example, a missing meeting link can be added from the session page in the dashboard.

Cancellation is safe to retry. Repeated DELETE /interviews/{id} requests return the canceled interview without changing its original canceled_at.

Polling for changes

Webhooks are not currently available. Use Synchronize interview changes for the polling loop, cursor handling, cancellations, and time-based statuses.

Rate limits

The REST routes do not publish rate-limit headers or a per-key rate-limit contract. Set a polling interval appropriate to your workflow and back off after errors. The MCP server has separate limits.

Webhooks

Webhooks are not currently available. Use polling to synchronize interviews. If your integration requires event notifications, contact support@litmushiring.com with your use case.

Versioning

The API is versioned under /api/v1. New response fields may be added; integrations should tolerate fields they do not use. Breaking changes use a new API version.