Responses and retries

Read both the HTTP status and the response body. A request sent to several channels can succeed on some and fail on others.

Successful requests

Most modern endpoints return their result inside data. Post lists also return paging. The legacy /profile and /post endpoints use different response shapes; see the API reference.

Partial success when creating posts

Example of a mixed result:

{
  "data": {
    "result": [
      {"profileId": "6512f0a1b2c3d4e5f6a7b8c9", "isScheduled": true},
      {"profileId": "6512f0a1b2c3d4e5f6a7b8ca", "isScheduled": false, "error": "The channel did not accept this post."}
    ]
  },
  "scheduled": ["6512f0a1b2c3d4e5f6a7b8c9"],
  "failed": [{"channelId": "6512f0a1b2c3d4e5f6a7b8ca", "reason": "The channel did not accept this post."}]
}

The API returns 200 when at least one channel succeeds, and 422 when a recognized per-channel result reports no successes. Other validation or upstream failures can return different error statuses.

Bulk scheduling does not guarantee rollback of the whole batch. Earlier posts can remain scheduled if a later operation fails. If a result contains outcomeUnknown: true, verify that post in the calendar before retrying. A timeout can also leave the result uncertain.

Common error bodies

Validation and permission errors usually look like this:

{"status": false, "message": "limit cannot be greater than 100."}

Some operations also return a machine-readable error:

{
  "status": false,
  "message": "The requested resource was not found.",
  "error": {"code": "NOT_FOUND", "retryable": false}
}

error.nextAction may provide a suggested next step. The top-level message is the explanation. These paths do not consistently provide a requestId or field-by-field details.

Failed REST authentication currently returns 400 with a body such as {"message": "Invalid token"}. Some other middleware can return 401.

Status codes

Code	What to do
400	Check the input, required fields, token, and query format.
401	Check credentials and reconnect if needed.
403	Check the token's scopes and account access.
404	Check the resource ID and whether it still exists.
409	Resolve the conflict, such as a duplicate label.
422	Check the per-channel failures or rejected content.
429	Wait for the time in Retry-After.
500, 502, 503	A service error occurred. Check write outcomes before retrying.

Avoid duplicate posts

1. Keep the response from each create or bulk request.
2. Check scheduled, failed, and data.result when present.
3. After a timeout or unknown outcome, check your scheduled posts or calendar.
4. Retry only the work you have confirmed did not succeed.

Sending an Idempotency-Key header does not make REST create requests safe to repeat. When contacting support, include the endpoint, time, HTTP status and response body, with tokens and private content removed.