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

# Errors and Idempotency

> How to think about duplicates, validation failures, and stable versus descriptive error strings.

# Errors and Idempotency

Phonefarm uses a mix of stable HTTP semantics and descriptive string-based validation messages.

## Idempotency Summary

| Endpoint family  | Idempotency key                                   |
| ---------------- | ------------------------------------------------- |
| Process creation | `(process_type, requested_by.system, request_id)` |
| Legacy ingest    | `(account_id, content_id)`                        |

## Duplicate Handling

### Process creation

Duplicate process creation returns the existing process payload with:

* `duplicate: true`
* `process_status`

### Legacy ingest

Duplicate ingest returns:

* `status: "duplicate"`
* existing `queue_item_id`
* existing `queue_status`

## HTTP Status Guidance

| Status code | Typical meaning                                                            |
| ----------- | -------------------------------------------------------------------------- |
| `200`       | Successful read, duplicate-compatible accept, or successful legacy cancel. |
| `202`       | Accepted process creation.                                                 |
| `401`       | Missing or invalid bearer token.                                           |
| `404`       | Missing process, account, or queue item.                                   |
| `409`       | State conflict such as non-cancellable item or race on update.             |
| `422`       | Validation error.                                                          |
| `500`       | Unexpected runtime, database, or environment failure.                      |

## Validation Error Strings

Many current validation failures are descriptive strings rather than versioned machine error codes.

Examples:

* `missing_fyp_judge_prompt`
* `missing_keyword_comment_plan_prompt`
* `needs_comment_plan:comment_plan_keys_must_match_keywords`
* `fyp_warmup_unattended_engagement_not_verified:like_probability_must_be_explicit_zero`

## Stability Guidance

Treat:

* HTTP status code as stable integration behavior
* response shape as stable within the current documented surface
* human-readable validation strings as descriptive, not as a formal enum unless you intentionally depend on them

## Retry Guidance

* Retry transport failures and `5xx` responses.
* Do not blindly retry `422` responses without fixing input data.
* Be careful retrying `409` responses because they are often state-dependent.
* For callback uncertainty, poll `GET /processes/{process_id}` rather than replaying create calls.

## Read Next

* [Process Lifecycle](../concepts/process-lifecycle)
* [Capability Requests](../api/capability-requests)
* [Ingest Legacy](../api/ingest-legacy)