Errors - Sapt

Every 4xx and 5xx response uses the same envelope:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Media 1: video must be at most 60 seconds for STORIES",
    "details": {}
  }
}

code is machine-readable and stable. message is written for a human and may change. details carries field-level validation errors when there are any.

Codes

HTTP	`code`	Means
400	`BAD_REQUEST`	The request was malformed, or media failed platform validation.
401	`UNAUTHORIZED`	Missing, malformed, or expired credential.
402	`PAYMENT_REQUIRED`	The workspace’s plan does not cover this call.
403	`FORBIDDEN`	Authenticated, but not permitted on this project.
404	`NOT_FOUND`	No such resource, or not visible to this credential.
409	`CONFLICT`	The resource changed underneath you.
412	`PRECONDITION_FAILED`	A required precondition was not met.
413	`PAYLOAD_TOO_LARGE`	The body exceeded the endpoint’s size limit.
422	`UNPROCESSABLE_CONTENT`	Well-formed, but semantically rejected.
429	`TOO_MANY_REQUESTS`	Rate limited — back off and retry.
500	`INTERNAL_SERVER_ERROR`	An unexpected failure on our side.
502	`BAD_GATEWAY`	An upstream platform (Meta, TikTok, Google) failed.
503	`SERVICE_UNAVAILABLE`	Temporarily unavailable.
504	`GATEWAY_TIMEOUT`	An upstream platform timed out.

Upstream platform failures

Publishing talks to Meta, TikTok, YouTube and Google. When one of those rejects a post, the failure surfaces two ways depending on when it happens:

Synchronously — the publish call returns 502 BAD_GATEWAY with the platform’s reason in message.
Asynchronously — a scheduled post moves to status: "failed" with the reason in errorMessage. Poll Get post status, and retry by calling Publish post immediately.

Retrying a failed post re-runs delivery. Retrying a post that actually succeeded upstream but failed to record can double-post. Check permalink on the post before retrying.