Retries and idempotency

One key per logical Start

Send an Idempotency-Key header with POST /sessions. Use 16–128 ASCII letters, digits, underscores, or hyphens. A UUID is a suitable value. The key belongs to your account. Replaying the same key with the same parsed JSON body returns the existing session identity instead of allocating another phone. JSON key ordering does not matter; changing fields or adding a formerly omitted default does.

curl --fail-with-body -sS https://api.phone-harness.com/sessions \
  -H "Authorization: Bearer $PHONE_HARNESS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -d '{"timeout_seconds":900}'

Without this header, each accepted POST can create another session.

Recover an ambiguous result

If your connection drops after sending the request, you may not know whether a phone was created. Look up the key:

curl --fail-with-body -sS \
  "https://api.phone-harness.com/sessions/requests/$REQUEST_KEY" \
  -H "Authorization: Bearer $PHONE_HARNESS_API_KEY"

Illustrative response

{
  "id": "examplephone",
  "request_key": "example-request-key-0001",
  "provider": "shlut",
  "state": "provisioning",
  "cleanup_complete": false,
  "cleanup_pending": false
}

Use the returned id to continue polling. If no receipt is found, retry the original POST with the same key and body. Even if the earlier request arrives late, the key prevents a second allocation for that logical request. Do not immediately generate another key because a request timed out.

Creation replay responses

Response	Meaning
`202`	The original session is returned. It may still be provisioning or closing.
`409`, `idempotency_conflict`	This key was already used with a different request body.
`410`, `create_request_completed`	That session has completed cleanup. Use a new key only when you intend to create another phone.
`503`, `create_request_recorded`	Admission was recorded, but the runtime is currently unavailable. Preserve the returned ID and recover the receipt; do not assume nothing was created.
`503`, `phones_busy`	Every phone is in use. Nothing was created and nothing is billed. Wait `retry_after_seconds` (also the `Retry-After` header) and send the same request again; the same idempotency key is fine.

The receipt remains available after the live session is removed. state: "recorded" is a receipt state, not API readiness. state: "released" and cleanup_complete: true confirm completed cleanup.

Operations are different

There is no general idempotency key for taps, text entry, app launches, or APK installation. A network failure does not prove the operation did not happen. Check the phone’s current state before repeating an action that could have side effects. For read-only polling, use bounded retries with backoff. If creation is refused for capacity, wait before retrying; repeatedly issuing new creation keys does not reserve future capacity.

Get started

Guides

Endpoints

Use cases

One key per logical Start

Recover an ambiguous result

Creation replay responses

Operations are different

​One key per logical Start

​Recover an ambiguous result

​Creation replay responses

​Operations are different

One key per logical Start

Recover an ambiguous result

Creation replay responses

Operations are different