Error Handling

API error codes, HTTP status codes, and error response format

The API uses standard HTTP status codes and returns structured error responses to help you handle failures programmatically.

Error response format

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_REQUIRED	401	API key is required. Include it as Authorization: Bearer <your-api-key>.
API_KEY_INVALID	401	The provided API key is not valid. Verify the key and try again.
API_KEY_EXPIRED	401	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_DISABLED	403	The API key is disabled. Enable it or create a new key.
NOT_A_MEMBER	403	The API key owner is not a member of this workspace.
LINK_DELETE_FORBIDDEN	403	You do not have permission to delete this link.
RECORDING_DELETE_FORBIDDEN	403	You do not have permission to delete this recording.
RECORDING_WORKSPACE_MISMATCH	403	Recording does not belong to this workspace.

Rate limiting

Error code	Status	Message
RATE_LIMITED	429	Rate limit exceeded. Wait and retry with exponential backoff.

Service errors

Error code	Status	Message
SERVICE_UNAVAILABLE	503	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_FOUND	404	Link not found
RECORDING_NOT_FOUND	404	Recording not found
PROJECT_NOT_FOUND	404	Project not found
WORKSPACE_NOT_FOUND	404	Workspace not found
LINK_GONE	410	Link has been deleted
RECORDING_GONE	410	Recording has already been deleted
PROJECT_GONE	410	Project has been deleted
LINK_PROJECT_DELETED	410	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_FAILED	500	Failed to create link
LINK_UPDATE_FAILED	500	Failed to update link
LINK_DELETE_FAILED	500	Failed to delete link
RECORDING_DELETE_FAILED	500	Failed to delete recording
LINK_DEFAULT_PROJECT_NOT_FOUND	404	No default project found for workspace
PLAN_LIMIT_EXCEEDED	403	Plan limit exceeded

API key management errors

These errors apply to the API Key Management endpoints, which use session authentication.

Error code	Status	Message
UNAUTHORIZED	401	You must be logged in to manage API keys.
API_KEY_ALREADY_EXISTS	409	You already have an API key. Revoke or rotate it instead.
API_KEY_NOT_FOUND	404	No API key found.
API_KEY_CREATE_FAILED	500	Failed to create API key.
API_KEY_REVOKE_FAILED	500	Failed to revoke API key.
API_KEY_ROTATE_FAILED	500	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.

Related

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