Skills Troubleshooting
Skills API failures are typed. Branch on error, details.category, and other
structured fields in the response. Do not parse message text, and do not log
API keys, OAuth tokens, prompts, generated source, validation fixtures,
customer payloads, connector credentials, or private skill outputs while
debugging.
Retry Rules
Retry only failures marked retryable by the API response or documented as temporary below. Use bounded exponential backoff with jitter, such as three attempts with a short initial delay and a maximum delay near 30 seconds. Stop retrying when the same non-retryable typed error repeats.
Failure Modes
| Failure | Common public signal | Retry | Developer action |
|---|---|---|---|
| Missing or invalid credentials | unauthorized or an authentication category | No | Send a valid developer API key in the x-api-key header from a trusted server boundary. See Authentication below. |
| Missing Skills scope | forbidden or an authorization category | No | Request the required scope: skills:read, skills:write, skills:execute, or skills:admin. |
| Public skill authorization failed | authorization_failed | No | Ensure the caller is trusted for the requested operation and has the required public Skills scope. |
| Generation quota exhausted | quota_exceeded with skill_generations | No | Reuse a shared-library skill, wait for reset, or ask the account owner to change the plan. |
| Validation quota exhausted | quota_exceeded with skill_validations | No | Stop creating validation attempts until the quota resets or the account limit changes. |
| Invocation quota exhausted | quota_exceeded with skill_invocations | No | Avoid retrying the same invocation. Reduce calls, reuse cached results, or wait for reset. |
| Library reuse quota exhausted | quota_exceeded with skill_library_reuses | No | Wait for reset or use a plan with higher reuse quota. |
| Billing action required | billing_required | No | Ask the account owner to resolve billing, upgrade, or remove the spend cap. |
| Billing state unavailable | billing_unavailable | Yes | Retry with bounded backoff because quota, credit, or account state could not be read. |
| Learning consent missing | learning_consent_required | No | Ask the account owner to approve learning terms or switch to private generation. |
| Reusable credit pending | credit_pending | Later | Wait for settlement to apply the accepted reusable-skill credit, then refresh account usage. |
| Invalid request shape | validation error or invalid_request | No | Fix the request body, schema fields, pagination bounds, or version selector. |
| Generation failed | terminal generation job failure category | No | Read the safe failureCategory and submit a corrected generation request. Do not retry the same payload blindly. |
| Validation failed | terminal validation verdict or validation failure category | No | Inspect the safe validation summary, fix inputs, grants, or behavior, and create a new candidate attempt. |
| Version unavailable | tool_version_unavailable, tool_version_retired, or tool_version_blocked | No | Select an available version, remove the pin, or handle the retired or blocked state in your UI. |
| Skill unavailable or not ready | tool_not_found, tool_not_ready, or availability category | No | Confirm the skill ID, tenant/workload authorization, validation state, and selected version. |
| Invocation execution failed | execution_failed, nested_execution_failed, or execution category | Maybe | Retry only if the structured response marks the failure retryable. Otherwise correct the request or dependency. |
| Library entry hidden or unauthorized | no result, visibility category, or policy-blocked reuse decision | No | Do not infer private entries from missing results. Choose another approved visible skill or generate privately. |
| Hosted-session action unavailable | hosted-session action availability category | No | Refresh the action list and execute only currently approved actions with supported public contracts. |
Authentication
The most common authentication mistake is sending the developer API key in the
wrong header. Developer API keys (the sk_live_ prefix) go in the x-api-key
header. The Authorization: Bearer header is verified as a JWT session token, so
a developer key sent that way is rejected as an invalid token and the request
returns an unauthorized failure.
- Use
x-api-key: sk_live_...for developer API keys. - Use
Authorization: Bearer ...only for short-lived JWT session tokens. - A
403/forbiddenafter a successful auth means the key is valid but lacks the required scope (skills:read,skills:write,skills:execute, orskills:admin). Mint or request a key with the missing scope.
Safe Diagnostics
When opening a support ticket, include public-safe identifiers and typed fields:
- Request timestamp and public request ID or correlation ID when available.
error,details.category, retryability, quota dimension, and safe reason code.- Generation job ID, invocation ID, skill ID, version ID, or hosted-session action ID when those IDs are already public to the account.
- The route and operation class, such as generation, validation, invocation, library reuse, or hosted-session action execution.
Do not include prompts, source code generated by the platform, validation input or output payloads, connector secrets, private customer records, account payment details, raw worker errors, stack traces from private execution, or bearer tokens.