Troubleshooting and recovery
Recover ambiguous submissions and diagnose model availability, quote conflicts, uploads and interrupted streams.
Keep useful evidence
Record the time, endpoint, HTTP status, business code, request_id and any taskId received. Separate an explicit rejection from a missing network response and a failure after acceptance. Never attach API keys, full prompts or original files to general logs or support requests.
Model missing or unavailable
Refresh the authenticated catalog and check enabled, available and the exact task model ID. A public model page does not establish account access. If 50301 persists, recheck availability and cap retries; repeated requests cannot open an unavailable model.
Invalid input or quote conflict
For 400, compare fields, types, enums and conditional requirements with the current inputSchema; remove unsupported parameters. For 40901, quote and confirm again because the request, validity window or price changed. Handle ordinary 409 by operation: a key bound to a different payload needs a corrected business association, not an endless retry.
Submission timed out without a task ID
Keep the original payload and Idempotency-Key. Recover the same submission within the valid window before deciding whether to create a new one. Once you have taskId, read recordInfo. Client timeouts, closed tabs and disconnected streams do not cancel accepted tasks; use state, cost and settled to determine the outcome.
Upload succeeded but input is rejected
A successful PUT still requires files/{fileId}/commit. Pass the returned spicy:// URI in a supported model input field, never uploadUrl. Check the signed Content-Type, size, format, owning account and expiry. Uploads last one day; retrying a task may require a new upload and updated input.
Missing callback or expired download
Check the HTTPS receiver, signature verification over original bytes and prompt success acknowledgement. Recover state with recordInfo and deduplicate callbacks before fulfilling an order. If a download URL expired while the output is retained, request another URL. Retry pending later; unavailable or expired output cannot be recovered by refreshing an old link.
Stream ends early
Check HTTP status and Content-Type before parsing SSE for your protocol. TCP chunks are not complete events, and socket closure is not a success marker. Inspect terminal events, error events and application deadlines. Do not assume a refund or resend at no cost after disconnecting; retain request_id and check usage records.
Balance, limits and support
For 40201 check available funds; for 40202 check account and key spending caps; for 429 follow Retry-After and reduce request frequency. Never send a key to support. Share reproduction steps, timestamps, request IDs and a redacted field structure, with expected and actual results.