Twitter API Errors & X Write Action Status

{
  "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
}

{
  "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
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "not_found",
  "message": "Resource not found."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

GET

write-actions

{id}

Twitter API Errors & X Write Action Status

curl --request GET \
  --url https://xquik.com/api/v1/x/write-actions/{id}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/write-actions/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "<string>",
  "id": "<string>",
  "writeActionId": "<string>",
  "action": "<string>",
  "status": "<string>",
  "terminal": true,
  "retryable": true,
  "safeToRetry": true,
  "statusUrl": "<string>",
  "pollAfterMs": {},
  "charged": true,
  "chargedCredits": "<string>",
  "billing": {},
  "request": {},
  "account": {},
  "target": {},
  "targetId": {},
  "result": {},
  "nextAction": {},
  "requestHash": "<string>",
  "requestId": "<string>",
  "idempotent": true,
  "error": "<string>",
  "message": "<string>",
  "sendDispatched": true,
  "sendDispatchedAt": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "completedAt": "<string>",
  "expiresAt": "<string>",
  "confirmedAt": "<string>",
  "confirmationCheckedAt": "<string>",
  "confirmationAttempts": 123,
  "tweetId": "<string>",
  "messageId": "<string>",
  "mediaId": "<string>",
  "mediaUrl": "<string>",
  "communityId": "<string>",
  "communityName": "<string>",
  "resultId": "<string>",
  "media": {},
  "details": {},
  "success": true
}

Every X write returns a durable x_write_action record. Store its id or writeActionId. Poll statusUrl whenever terminal is false.

Handle Twitter API Errors

Use this endpoint for Twitter API error handling after an Xquik write. Xquik adds a durable write record beside ordinary HTTP response codes. 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 same durable action.

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.

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

string

Send your Xquik API key in this header.

string

Send an OAuth 2.1 bearer token instead of x-api-key.

Path Parameters

string

required

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

string

Always x_write_action.

string

Durable action ID.

string

This field aliases id.

string

Exact write operation.

string

Current lifecycle status.

boolean

This field is true when polling can stop.

boolean

This field is true when a later attempt could succeed.

boolean

This field is true when a new attempt is safe.

string

Relative polling URL.

number | null

Recommended polling delay.

boolean

true after billing settles as charged.

string

Settled credits charged.

object

Planned and settled billing state.

object

Stable hash and exact sanitized payload.

object

Connected account selected for this write.

object | null

Target type and ID.

string | null

Target ID alias.

object | null

Confirmed result or desired state.

object | null

Required poll, retry, or verification step.

string

Stable request fingerprint.

string

Correlation ID echoed in X-Request-Id.

boolean

true when this response replays an action.

string

Machine-readable error code.

string

Actionable status or error message.

boolean

This field is true after dispatch.

string

ISO 8601 dispatch time.

string

ISO 8601 creation time.

string

ISO 8601 latest update time.

string

ISO 8601 terminal time.

string

Nonterminal resolution deadline.

string

ISO 8601 confirmation time.

string

ISO 8601 latest confirmation check.

number

Confirmation attempt count.

string

Confirmed tweet ID when available.

string

Confirmed direct message ID when available.

string

Confirmed media ID when available.

string

Public media URL when available.

string

Confirmed community ID when available.

string

Confirmed community name when available.

string

Result ID alias.

object

Media details when used.

object

Structured recovery context.

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

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

Idempotency replay protection remains active for at least 90 days.

{
  "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
}

{
  "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
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "not_found",
  "message": "Resource not found."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

Twitter API Errors & X Write Action Status

curl --request GET \
  --url https://xquik.com/api/v1/x/write-actions/{id}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/write-actions/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "<string>",
  "id": "<string>",
  "writeActionId": "<string>",
  "action": "<string>",
  "status": "<string>",
  "terminal": true,
  "retryable": true,
  "safeToRetry": true,
  "statusUrl": "<string>",
  "pollAfterMs": {},
  "charged": true,
  "chargedCredits": "<string>",
  "billing": {},
  "request": {},
  "account": {},
  "target": {},
  "targetId": {},
  "result": {},
  "nextAction": {},
  "requestHash": "<string>",
  "requestId": "<string>",
  "idempotent": true,
  "error": "<string>",
  "message": "<string>",
  "sendDispatched": true,
  "sendDispatchedAt": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "completedAt": "<string>",
  "expiresAt": "<string>",
  "confirmedAt": "<string>",
  "confirmationCheckedAt": "<string>",
  "confirmationAttempts": 123,
  "tweetId": "<string>",
  "messageId": "<string>",
  "mediaId": "<string>",
  "mediaUrl": "<string>",
  "communityId": "<string>",
  "communityName": "<string>",
  "resultId": "<string>",
  "media": {},
  "details": {},
  "success": true
}

Overview

X API

X Write

Trends

Radar

Account

API Keys

Guest Wallets

Credits

X Accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter API Errors & X Write Action Status

Handle Twitter API Errors

Agent Algorithm

Lifecycle

Request

Headers

Path Parameters

Response

Retry Rules

​Handle Twitter API Errors

​Agent Algorithm

​Lifecycle

​Request

​Headers

​Path Parameters

​Response

​Retry Rules

Handle Twitter API Errors

Agent Algorithm

Lifecycle

Request

Headers

Path Parameters

Response

Retry Rules