Error codes

All Kynasmith API errors follow a consistent envelope:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description of what went wrong.",
    "retryable": false,
    "details": {}
  }
}

code — A machine-readable string identifying the error type.
message — A human-readable explanation. Do not parse this programmatically.
retryable — Whether the request can be retried without changes.
details — Additional structured context (varies by error code).

General API errors

Code	HTTP Status	Retryable	Description	Recommended Action
`access_token_missing`	401	No	No `Authorization: Bearer` header provided.	Add a valid bearer token to the request.
`access_token_invalid`	401	No	The access token is malformed or has been revoked.	Mint a new access token.
`access_token_expired`	401	Yes	The access token has expired.	Refresh or re-mint the access token.
`insufficient_scope`	403	No	The token does not have the required scope for this operation.	Mint a token with the required scopes. See scopes reference.
`project_mismatch`	403	No	The `project_id` in the request does not match the token’s project scope.	Use the correct project ID or mint a token for the target project.
`authorization_failed`	403	No	General authorization failure.	Check that your credential has access to the requested resource.
`not_found`	404	No	The requested resource does not exist.	Verify the resource ID.
`validation_error`	422	No	The request body failed schema validation.	Check the `details` field for specific field errors.
`conflict`	409	No	The operation conflicts with the current resource state.	Read the current resource state and retry with the correct preconditions.
`rate_limited`	429	Yes	Too many requests. See Rate limits.	Back off and retry after the `Retry-After` header duration.
`internal_error`	500	Yes	An unexpected server error occurred.	Retry with exponential backoff. If persistent, contact support with the `X-Request-ID`.
`service_unavailable`	503	Yes	The service is temporarily unavailable.	Retry with exponential backoff.

MoveSpec errors

Code	HTTP Status	Retryable	Description	Recommended Action
`movespec_not_found`	404	No	The MoveSpec resource does not exist.	Verify the `movespec_id`.
`movespec_version_not_found`	404	No	The MoveSpec version does not exist.	Verify the `movespec_version_id`.
`draft_validation_failed`	422	No	The draft YAML has blocking validation errors.	Fix the errors listed in the validation response, then re-validate.
`version_already_released`	409	No	The version is already in the released state.	No action needed — the version is already active.
`no_released_version`	404	No	The MoveSpec has no released version to resolve at runtime.	Release an immutable version before creating sessions.

Detection session errors

Code	HTTP Status	Retryable	Description	Recommended Action
`session_not_found`	404	No	The detection session does not exist.	Verify the `session_id`.
`session_already_completed`	409	No	The session has already reached a terminal state.	Create a new session.
`session_already_cancelled`	409	No	The session was cancelled.	Create a new session.
`contract_version_unsupported`	422	No	Your SDK version is not compatible.	Update your SDK to the latest version.
`duplicate_active_connection`	409	No	Another WebSocket connection is already active for this session.	Close the existing connection before reconnecting.

Billing and quota errors

These errors are returned when operations are denied due to billing or plan limits.

Code	HTTP Status	Retryable	Description	Recommended Action
`quota_exceeded`	403	No	Your organization has exceeded its plan’s usage quota.	Upgrade your plan or wait for the quota reset. Check `details.quota_limit`, `details.current_usage`, and `details.resets_at`.
`organization_suspended`	403	No	The organization has been suspended.	Contact support or resolve the suspension reason in the portal.
`delinquent_payment`	403	No	The organization has an overdue payment.	Update your payment method in the portal at app.kynasmith.dev.
`plan_requires_upgrade`	403	No	The requested feature is not available on your current plan.	Upgrade your plan in the portal.
`billing_not_configured`	403	No	Billing has not been set up for this organization.	Configure billing in the portal under Settings > Billing.

Billing error response example

{
  "error": {
    "code": "quota_exceeded",
    "message": "Organization has exceeded the monthly accepted-frames quota.",
    "retryable": false,
    "details": {
      "quota_limit": 10000,
      "current_usage": 10001,
      "resets_at": "2026-05-01T00:00:00Z",
      "upgrade_url": "https://app.kynasmith.dev/settings/billing"
    }
  }
}

Distinguishing rate limits from billing errors

Rate limiting (rate_limited / HTTP 429): Abuse protection that applies equally to all customers. Retry after the indicated duration.
Billing errors (quota_exceeded, plan_requires_upgrade / HTTP 403): Plan-based limits tied to your organization. These require a plan change or waiting for quota reset, not just retrying.

Both SDKs map these to distinct error types (RateLimitError vs. AuthorizationError) so you can handle them differently in your code.

Guides

Error handling

Endpoints

machine-auth

detection

health

movespecs

platform

Error codes

Error codes

General API errors

MoveSpec errors

Detection session errors

Billing and quota errors

Billing error response example

Distinguishing rate limits from billing errors

​Error codes

​General API errors

​MoveSpec errors

​Detection session errors

​Billing and quota errors

​Billing error response example

​Distinguishing rate limits from billing errors

Error codes

General API errors

MoveSpec errors

Detection session errors

Billing and quota errors

Billing error response example

Distinguishing rate limits from billing errors