Write action status & errors, X (Twitter) API docs

GET https://xquik.com/api/v1/x/write-actions/{id} Every X write returns a stored x_write_action record. Store its id or writeActionId. Poll statusUrl whenever terminal is false.

Handle X (Twitter) API errors

Use this endpoint to handle errors after an Xquik write. Xquik stores a write record in addition to the HTTP response code. An error message does not prove that a write failed. A timeout can occur after dispatch. Trust terminal, safeToRetry, sendDispatched, and nextAction. Review X’s response codes and errors. Xquik’s write status record uses different fields.

Trust terminal, safeToRetry, and nextAction. Never infer retry safety from an HTTP status or error name alone.

Agent algorithm

Generate one unique Idempotency-Key for the intended write.
Submit the write once.
Store id, request.hash, account, target, billing, and statusUrl.
When terminal is false, wait for Retry-After or pollAfterMs.
Poll statusUrl until terminal is true.
Record result and settled billing.
Retry only when safeToRetry is true, using a new key.
When nextAction.type is verify_result, verify the external state first.

Reuse the original Idempotency-Key only to replay the same account, action, target, and payload. The replay returns the first answer again. It keeps the first status, body, and Retry-After, and adds idempotent: true. While the first request runs, the replay returns 202 and the action. A replay sends nothing to X and charges nothing.

Lifecycle

Status	Terminal	Required behavior
`accepted`	No	Poll. Dispatch has not completed.
`dispatching`	No	Poll. Do not submit another write.
`pending_confirmation`	No	Poll. The write may already exist.
`success`	Yes	Store the result and settled billing.
`failed`	Yes	Follow `safeToRetry` and `nextAction`.
`expired`	Yes	Verify the result when dispatch may have occurred.

Writes X never confirms end expired. You pay nothing for them. Their message can read “X did not confirm this action. Check your X account before you retry.” A post X never published fails as x_post_not_sent. You pay nothing, and safeToRetry is true. Active actions return 202, Location, and Retry-After. Terminal actions return 200 from this endpoint.

Request

curl https://xquik.com/api/v1/x/write-actions/42 \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

const response = await fetch("https://xquik.com/api/v1/x/write-actions/42", {
  headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
});
const action = await response.json();

if (!action.terminal) {
  const delayMs = action.pollAfterMs ?? 2000;
  process.stdout.write(JSON.stringify({ delayMs, next: action.statusUrl }) + "\n");
} else if (action.safeToRetry) {
  process.stdout.write("Ask for approval, then retry with a new key.\n");
} else {
  process.stdout.write(JSON.stringify(action.result) + "\n");
}

import requests

response = requests.get(
    "https://xquik.com/api/v1/x/write-actions/42",
    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
)
action = response.json()

if not action["terminal"]:
    print({"delay_ms": action["pollAfterMs"], "next": action["statusUrl"]})
elif action["safeToRetry"]:
    print("Ask for approval, then retry with a new key.")
else:
    print(action["result"])

Headers

Header	Type	Required	Description
`x-api-key`	`string`	No	Send your Xquik API key in this header.
`Authorization`	`string`	No	Send an OAuth 2.1 bearer token instead of `x-api-key`.

Path parameters

Path parameter	Type	Required	Description
`id`	`string`	Yes	Action ID returned by the original write.

Response

200 Terminal
202 Active
401 Unauthenticated
404 Not found
429 Rate limited

Polling is complete. Store result and settled billing. Follow safeToRetry and nextAction before any new attempt.

Poll statusUrl after Retry-After or pollAfterMs. Never submit another write while terminal is false.

Wait for Retry-After. Poll the same action again. Never resend the write.

Field	Type	Description
`object`	`string`	Always `x_write_action`.
`id`	`string`	Durable action ID.
`writeActionId`	`string`	This field aliases `id`.
`action`	`string`	Exact write operation.
`status`	`string`	Current lifecycle status.
`terminal`	`boolean`	This field is `true` when polling can stop.
`retryable`	`boolean`	This field is `true` when a later attempt could succeed.
`safeToRetry`	`boolean`	This field is `true` when a new attempt is safe.
`statusUrl`	`string`	Relative polling URL.
`pollAfterMs`	`number \| null`	Recommended polling delay.
`charged`	`boolean`	`true` after billing settles as charged.
`chargedCredits`	`string`	Settled credits charged.
`billing`	`object`	Planned and settled billing state.
`request`	`object`	Stable hash and exact sanitized payload.
`account`	`object`	Connected account selected for this write.
`target`	`object \| null`	Target type and ID.
`targetId`	`string \| null`	Target ID alias.
`result`	`object \| null`	Confirmed result or desired state.
`nextAction`	`object \| null`	Required poll, retry, or verification step.
`requestHash`	`string`	Stable request fingerprint.
`requestId`	`string`	Correlation ID echoed in `X-Request-Id`.
`idempotent`	`boolean`	`true` when this response answers a retry with the same `Idempotency-Key`.
`error`	`string`	Machine-readable error code.
`message`	`string`	Actionable status or error message.
`sendDispatched`	`boolean`	This field is `true` after dispatch.
`sendDispatchedAt`	`string`	ISO 8601 dispatch time.
`createdAt`	`string`	ISO 8601 creation time.
`updatedAt`	`string`	ISO 8601 latest update time.
`completedAt`	`string`	ISO 8601 terminal time.
`expiresAt`	`string`	Nonterminal resolution deadline.
`confirmedAt`	`string`	ISO 8601 confirmation time.
`confirmationCheckedAt`	`string`	ISO 8601 latest confirmation check.
`confirmationAttempts`	`number`	Confirmation attempt count.
`tweetId`	`string`	Confirmed tweet ID when available.
`messageId`	`string`	Confirmed direct message ID when available.
`mediaId`	`string`	Confirmed media ID when available.
`mediaUrl`	`string`	Public media URL when available.
`communityId`	`string`	Confirmed community ID when available.
`communityName`	`string`	Confirmed community name when available.
`resultId`	`string`	Result ID alias.
`media`	`object`	Media details when used.
`details`	`object`	Structured recovery context.
`success`	`boolean`	This field is `true` when status equals `success`.

{
  "object": "x_write_action",
  "id": "42",
  "writeActionId": "42",
  "action": "create_tweet",
  "status": "pending_confirmation",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/42",
  "pollAfterMs": 2000,
  "billing": {
    "status": "pending",
    "charged": false,
    "plannedCredits": "30",
    "chargedCredits": "0"
  },
  "request": {
    "hash": "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "payload": { "text": "Hello" }
  },
  "account": { "id": "8", "username": "agent_account" },
  "target": null,
  "result": null,
  "nextAction": {
    "type": "poll",
    "url": "/api/v1/x/write-actions/42",
    "afterMs": 2000
  },
  "sendDispatched": true,
  "success": false
}

Retry rules

With retryable: false and safeToRetry: false, do not retry.
With retryable: true and safeToRetry: false, verify the result first.
With safeToRetry: true, request approval and retry using a new key.
With terminal: false, keep polling, even when the original HTTP response was an error.

Xquik keeps idempotency replay protection for at least 90 days.

Response examples

200 example

{
  "object": "x_write_action",
  "id": "12345",
  "writeActionId": "12345",
  "action": "like",
  "status": "success",
  "terminal": true,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": null
}

202 example

{
  "object": "x_write_action",
  "id": "12346",
  "writeActionId": "12346",
  "action": "create_tweet",
  "status": "dispatching",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12346",
  "pollAfterMs": 2000
}

400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
404 { "error": "not_found", "message": "Resource not found." }
429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }

​Handle X (Twitter) API errors

​Agent algorithm

​Lifecycle

​Request

​Headers

​Path parameters

​Response

​Retry rules

​Response examples

​200 example

​202 example

Handle X (Twitter) API errors

Agent algorithm

Lifecycle

Request

Headers

Path parameters

Response

Retry rules

Response examples

200 example

202 example