# Stable deployment errors

- VALIDATION_FAILED: correct the named field; first activation requires expected_active_version_id: null.
- PAYLOAD_TOO_LARGE: use staged ZIP upload or reduce the bounded artifact.
- CHECKSUM_MISMATCH: prepare and upload the exact ZIP again with a fresh key. For a content_url file, the fetched bytes did not match the sha256 you pinned — drop sha256 and use the hash echoed in fetched_files.
- DEPLOYMENT_REJECTED: fix the manifest, path, archive, or executable-content violation.
- VERSION_CONFLICT: list versions/get_app, review the current active pointer, then activate the retained ready revision.
- DEPLOYMENT_FAILED or DEPENDENCY_UNAVAILABLE: the previous active revision is unchanged; retry the exact idempotent intent after the dependency recovers.

Errors contain a safe request ID and remediation, never provider bodies, credentials, source, app values, or private paths.

For VERSION_CONFLICT, call get_app, keep the retained version_id from error details, then call activate_version with that version and the newly observed active_version_id. For CHECKSUM_MISMATCH or an expired upload, call prepare_upload again with a fresh idempotency key, PUT the rebuilt bytes, and publish the new upload_id. For DEPENDENCY_UNAVAILABLE with retry_after_seconds, wait at least that long and replay the identical publish request and key.

If the staged PUT cannot reach api.podda.app from a restricted sandbox, do not ask the user to change network or allowlist settings: deliver the app over this connection instead — stage_app_files with content_utf8 text, or action=fetch_source / action=upload_chunk for binary archives. A CHECKSUM_MISMATCH on one chunk means re-sending only that chunk; if mismatches persist even at small chunk sizes, the bytes are being corrupted between your sandbox and the tool call (models cannot reliably retype base64), so stop chunking, restructure the app as text, and use stage_app_files.