API errors
UniPost errors are designed to be actionable without parsing provider payloads. Preserve the structured fields, show request_id in support surfaces, and use /v1/posts as the canonical publishing route family.
Error envelope
| Parameter | Type | Required | Description |
|---|---|---|---|
| error.code | string | ✓ | Stable API error code. Existing CLI output normalizes this value for backward compatibility. |
| error.normalized_code | string | ✓ | Lowercase machine-readable alias for routing and support automation. |
| error.message | string | ✓ | Customer-safe summary of what failed. |
| error.hint | string | X | Short remediation guidance when UniPost can safely suggest one. |
| error.next_action | string | X | Stable action enum for client UI and automation. Present only on actionable errors. |
| error.is_retriable | boolean | X | Whether retrying the same request later is expected to help. |
| error.error_source | string | X | Where the failure originated: unipost, platform, worker, or unknown. |
| error.error_temporality | string | X | Whether the condition is temporary, permanent, or unknown. |
| error.provider_error | object | X | Sanitized provider fields such as provider, http_status, code, subcode, type, reason, domain, quota_limit, quota_location, and is_transient. |
| error.retry_policy | object | X | Best-effort retry snapshot. Use will_retry for automatic retry state; use is_retriable for retry eligibility. |
| error.docs_url | string | X | Relevant documentation URL for the failed request. |
| error.issues | array | X | Field-level validation issues. Preserve this array in clients instead of parsing message text. |
| request_id | string | ✓ | Request identifier to include when contacting support. |
Validation issues
Validation details appear in error.issues for failed create requests and in data.errors or data.warnings from POST/v1/posts/validate. Client UIs should render these fields directly instead of matching strings in error.message.
| Parameter | Type | Required | Description |
|---|---|---|---|
| platform_post_index | integer | X | 0-based index from platform_posts[] when the issue belongs to one destination. |
| account_id | string | X | Connected account associated with the issue. |
| platform | string | X | Resolved platform, such as tiktok, instagram, youtube, or linkedin. |
| field | string | X | Request field that needs a change, for example caption or platform_options.youtube.title. |
| code | string | ✓ | Machine-readable issue code, such as exceeds_max_length or missing_required_field. |
| message | string | ✓ | Customer-facing explanation for this one issue. |
| hint | string | X | Specific fix guidance for this issue. |
| next_action | string | X | Action enum for blocking validation errors. |
| actual | any | X | Actual submitted value or count when useful for debugging. |
| limit | any | X | Platform limit that was exceeded or missed. |
| severity | string | ✓ | error for blocking issues, warning for non-blocking issues. |
Publish failure fields
Failed per-account results returned by GET/v1/posts/:post_id include structured failure fields. Use error_source to distinguish UniPost, worker, and official platform failures. Use error_temporality to distinguish temporary, permanent, and unknown conditions. Use retry_policy.will_retry to know whether UniPost has actually scheduled automatic retry; is_retriable only means retrying may help. Do not parse error_message for branching.
| Code | HTTP | Description |
|---|---|---|
| validation_error | 400 | The request or post payload is invalid. Inspect issues and fix the listed fields. |
| platform_request_invalid | 400 | The provider rejected platform options or metadata. Review privacy, title, disclosure, or content options. |
| media_error | 400 | The provider rejected media format, dimensions, duration, URL, or processing state. |
| temporary_platform_error | 503 | The platform or async worker path failed transiently. Check retry_policy.will_retry to know whether UniPost scheduled retry. |
| rate_limit | 429 | Wait before retrying. Respect Retry-After when present. |
| account_reconnect_required | 409 | Reconnect the affected social account before retrying. |
| missing_permission | 403 | Reconnect or update platform permissions and scopes. |
| target_not_found | 404 | The selected platform target no longer exists or is not visible to the account. |
| platform_error | 502 | A provider failure that UniPost cannot classify more specifically. |
| unknown_error | 500 | The failure is unknown. Contact support with request_id. |
next_action values
| Parameter | Type | Required | Description |
|---|---|---|---|
| fix_request | validation | X | Change the request payload, then validate again. |
| shorten_caption | validation | X | Shorten the caption or title to the platform limit. |
| review_platform_options | publish | X | Check privacy, disclosure, content, or destination options for the platform. |
| fix_media | publish | X | Replace or re-encode the media to meet platform requirements. |
| retry_later | publish | X | The platform or worker path is temporarily unavailable. |
| wait_and_retry | rate limit | X | Respect Retry-After or wait before sending the same request again. |
| review_quota | quota | X | Reduce usage or upgrade capacity before retrying. |
| reconnect_account | auth | X | Reconnect the affected social account. |
| reconnect_or_update_permissions | auth | X | Reconnect with the required scopes or permissions. |
| select_valid_target | publish | X | Choose a valid account, page, board, post, or other platform target. |
| contact_support | support | X | Send the request_id to UniPost support. Do not parse provider payloads yourself. |
Route naming
The canonical public publishing routes are /v1/posts, /v1/posts/validate, and /v1/posts/:post_id. Older client references to /v1/social-posts should be migrated to /v1/posts; new docs, CLI, MCP, and SDK examples use the canonical route names.