Skip to main content

​
Errors and Idempotency

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

​
Idempotency Summary

​
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

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