> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> Every error code the Artifacta API returns, with recommended agent actions.

## Error response shape

Every error returns this structure:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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. |

<Info>
  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).
</Info>

## 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`) |

```python theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.