The API uses standard HTTP status codes and returns structured error responses to help you handle failures programmatically.
Error responses include an error code for programmatic handling, a human-readable message, and a link to the relevant documentation:
{ "error" : "API_KEY_REQUIRED" , "message" : "API key is required. Include it as Authorization: Bearer <your-api-key>. See https://docs.userplane.io/api/authentication" }
Authentication errors Returned when the API key is missing, invalid, or expired.
Error code Status Message API_KEY_REQUIRED401 API key is required. Include it as Authorization: Bearer <your-api-key>. API_KEY_INVALID401 The provided API key is not valid. Verify the key and try again. API_KEY_EXPIRED401 The API key has expired. Rotate or create a new key.
Authorization errors Returned when the authenticated user lacks access to the requested resource.
Error code Status Message API_KEY_DISABLED403 The API key is disabled. Enable it or create a new key. NOT_A_MEMBER403 The API key owner is not a member of this workspace. LINK_DELETE_FORBIDDEN403 You do not have permission to delete this link. RECORDING_DELETE_FORBIDDEN403 You do not have permission to delete this recording. RECORDING_WORKSPACE_MISMATCH403 Recording does not belong to this workspace.
Rate limiting Error code Status Message RATE_LIMITED429 Rate limit exceeded. Wait and retry with exponential backoff.
Service errors Error code Status Message SERVICE_UNAVAILABLE503 API key verification service is temporarily unavailable. Please try again later.
See Rate Limits for details on limits and retry strategies.
Resource errors Returned when the requested resource does not exist or has been deleted.
Error code Status Message LINK_NOT_FOUND404 Link not found RECORDING_NOT_FOUND404 Recording not found PROJECT_NOT_FOUND404 Project not found WORKSPACE_NOT_FOUND404 Workspace not found LINK_GONE410 Link has been deleted RECORDING_GONE410 Recording has already been deleted PROJECT_GONE410 Project has been deleted LINK_PROJECT_DELETED410 Project has been deleted
A 410 Gone response indicates the resource was soft-deleted. Unlike 404 Not Found, this
confirms the resource previously existed.
Mutation errors Returned when a create, update, or delete operation fails.
Error code Status Message LINK_CREATE_FAILED500 Failed to create link LINK_UPDATE_FAILED500 Failed to update link LINK_DELETE_FAILED500 Failed to delete link RECORDING_DELETE_FAILED500 Failed to delete recording LINK_DEFAULT_PROJECT_NOT_FOUND404 No default project found for workspace PLAN_LIMIT_EXCEEDED403 Plan limit exceeded
API key management errors These errors apply to the API Key Management endpoints, which use session authentication.
Error code Status Message UNAUTHORIZED401 You must be logged in to manage API keys. API_KEY_ALREADY_EXISTS409 You already have an API key. Revoke or rotate it instead. API_KEY_NOT_FOUND404 No API key found. API_KEY_CREATE_FAILED500 Failed to create API key. API_KEY_REVOKE_FAILED500 Failed to revoke API key. API_KEY_ROTATE_FAILED500 Failed to rotate API key.
Best practices
Check HTTP status first — use the status code to determine the error category (4xx = client error, 5xx = server error).Use the error field for programmatic handling — match on error codes like API_KEY_EXPIRED or RATE_LIMITED in your code.Use the message field for logging — the message provides human-readable context for debugging.Retry on 429 and 5xx — these are transient and may succeed on retry with backoff.Do not retry on 4xx (except 429) — these indicate a client-side issue that needs to be fixed.
Rate Limits Rate limit thresholds and retry strategies
Authentication API key authentication and authorization scopes
Pagination Page-based pagination for list endpoints
Best Practices Build reliable integrations that handle errors gracefully
