Skip to main content

​
Errors and Idempotency

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

​
Idempotency Summary

Endpoint familyIdempotency 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 codeTypical meaning
200Successful read, duplicate-compatible accept, or successful legacy cancel.
202Accepted process creation.
401Missing or invalid bearer token.
404Missing process, account, or queue item.
409State conflict such as non-cancellable item or race on update.
422Validation error.
500Unexpected 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
  • capability_not_live_verified:fyp_warmup

​
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.