Error Reference

Error response shape

Every error returns this structure:

{
  "error": {
    "code": "artifact_not_found",
    "message": "Artifact art_xxx was not found.",
    "status": 404
  }
}

code — stable, machine-readable string. Match on this. Part of the V1 API contract.
message — human-readable. May change without notice. Do not parse.
status — HTTP status code (duplicated in the body for convenience).

For rate limit errors, an additional field is included:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 5 seconds.",
    "status": 429,
    "retry_after_seconds": 5
  }
}

Complete error code reference

Code	HTTP	Meaning	Agent action
`invalid_request`	400	Malformed body, missing fields, invalid metadata key	Abort. Fix the request. Same input always fails.
`ttl_exceeds_plan_limit`	400	TTL exceeds plan max (Free: 90d, Pro: 365d)	Retry with shorter TTL or escalate for upgrade.
`upload_not_found`	400	`complete` called but blob missing in R2	Retry the PUT upload, then call `complete` again.
`unauthorized`	401	Invalid, missing, or revoked API key	Abort immediately. Do not retry. Check or rotate key.
`quota_exceeded`	403	Storage or request quota reached. Also returned when a Free-tier tenant attempts to publish a password-protected Artifact Page (`access: "password"` requires Pro).	Abort. Delete old artifacts or upgrade plan.
`artifact_not_found`	404	No artifact with this ID for this tenant	Abort. Stale reference. Re-query to find correct artifact.
`session_not_found`	404	No artifacts exist for this session (seal endpoint only)	Abort. Verify the session ID.
`session_sealed`	409	Upload to a sealed session	Use a different session. No unseal operation exists.
`artifact_expired`	410	Artifact’s TTL has passed	Abort. Re-generate from source. Cannot recover.
`artifact_already_deleted`	410	Artifact was soft-deleted	Treat as success if intent was to delete. Otherwise, artifact is gone.
`file_too_large`	413	Exceeds size limit	Switch method. Direct: 500 MB max. Presigned: 5 GB max.
`rate_limited`	429	Burst limit exceeded (100 req/s sustained). Also returned by the Artifact Pages `/unlock` and `/report` endpoints after the per-slug/per-IP attempt cap is reached.	Retry after `retry_after_seconds`. Implement exponential backoff.

These error codes are part of the V1 API contract. Existing codes will not be removed or renamed without a new API version. New codes may be added (non-breaking).

SDK exception mapping

The Python SDK maps each error code to a typed exception:

Exception	API error code
`ArtifactaError`	Base class for all errors
`InvalidRequestError`	`invalid_request`
`UnauthorizedError`	`unauthorized`
`QuotaExceededError`	`quota_exceeded`
`ArtifactNotFoundError`	`artifact_not_found`
`ArtifactExpiredError`	`artifact_expired`
`SessionSealedError`	`session_sealed`
`TTLExceedsPlanLimitError`	`ttl_exceeds_plan_limit`
`RateLimitedError`	`rate_limited` (includes `.retry_after_seconds`)

from artifacta import Client, ArtifactNotFoundError, ArtifactExpiredError

client = Client()

try:
    artifact = client.get("art_2xk9f7v3m1p0")
except ArtifactNotFoundError:
    print("Artifact was never created or ID is wrong")
except ArtifactExpiredError:
    print("Artifact existed but TTL passed — re-generate from source")

CLI exit codes

Exit code	Meaning
`0`	Success
`1`	Client error (bad input, auth failure, not found)
`2`	Server error
`3`	Network error

Getting Started

Guides

Reference

Error response shape

Complete error code reference

SDK exception mapping

CLI exit codes

​Error response shape

​Complete error code reference

​SDK exception mapping

​CLI exit codes

Error response shape

Complete error code reference

SDK exception mapping

CLI exit codes