> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Twitter API Errors & X Write Action Status
> Handle Twitter API errors by polling tweet, reply, DM, follow, like, repost, media, profile, and community writes. Check results, billing, and safe retries.
```json theme={null}
{
"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
}
```
```json theme={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
}
```
```json theme={null}
{
"error": "unauthenticated",
"message": "Authentication required. Provide a valid API key or bearer token."
}
```
```json theme={null}
{
"error": "not_found",
"message": "Resource not found."
}
```
```json theme={null}
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Try again later.",
"retryAfter": 60
}
```
For the complete documentation index, see llms.txt.
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](https://docs.x.com/x-api/fundamentals/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
1. Generate one unique `Idempotency-Key` for the intended write.
2. Submit the write once.
3. Store `id`, `request.hash`, `account`, `target`, `billing`, and `statusUrl`.
4. When `terminal` is `false`, wait for `Retry-After` or `pollAfterMs`.
5. Poll `statusUrl` until `terminal` is `true`.
6. Record `result` and settled `billing`.
7. Retry only when `safeToRetry` is `true`, using a new key.
8. 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
```bash cURL theme={null}
curl https://xquik.com/api/v1/x/write-actions/42 \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
```javascript Node.js theme={null}
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");
}
```
```python Python theme={null}
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
Send your Xquik API key in this header.
Send an OAuth 2.1 bearer token instead of `x-api-key`.
## Path Parameters
Durable action ID returned by the original write.
## Response
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`.
Fix the authentication credentials. Keep the original write record.
Check the action ID and environment. Never resubmit the original write.
Wait for `Retry-After`. Poll the same action again. Never resend the write.
Always `x_write_action`.
Durable action ID.
This field aliases `id`.
Exact write operation.
Current lifecycle status.
This field is `true` when polling can stop.
This field is `true` when a later attempt could succeed.
This field is `true` when a new attempt is safe.
Relative polling URL.
Recommended polling delay.
`true` after billing settles as charged.
Settled credits charged.
Planned and settled billing state.
Stable hash and exact sanitized payload.
Connected account selected for this write.
Target type and ID.
Target ID alias.
Confirmed result or desired state.
Required poll, retry, or verification step.
Stable request fingerprint.
Correlation ID echoed in `X-Request-Id`.
`true` when this response replays an action.
Machine-readable error code.
Actionable status or error message.
This field is `true` after dispatch.
ISO 8601 dispatch time.
ISO 8601 creation time.
ISO 8601 latest update time.
ISO 8601 terminal time.
Nonterminal resolution deadline.
ISO 8601 confirmation time.
ISO 8601 latest confirmation check.
Confirmation attempt count.
Confirmed tweet ID when available.
Confirmed direct message ID when available.
Confirmed media ID when available.
Public media URL when available.
Confirmed community ID when available.
Confirmed community name when available.
Result ID alias.
Media details when used.
Structured recovery context.
This field is `true` when status equals `success`.
```json theme={null}
{
"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.