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 extra context when there is any. For a VALIDATION_ERROR it holds issues, one { path, code, message } entry per field that failed.

Codes

HTTP	`code`	Means
400	`BAD_REQUEST`	The request was malformed, or media failed platform validation.
400	`VALIDATION_ERROR`	The path, query or body did not match the endpoint’s schema.
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.
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.

Branch on code, not only on the HTTP status. A few codes, including PAYLOAD_TOO_LARGE, UNPROCESSABLE_CONTENT and TIMEOUT, currently arrive with HTTP 400.

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 an error with the platform’s reason in message, and the post moves to status: "failed".
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.