Errors

Pozy uses HTTP status codes and returns a JSON body on every failed request. Branch your code on the HTTP status and the code field. Show error to people, but never parse it: the wording can change.

#The error envelope

{
  "error": "`name` must be 1 to 50 characters.",
  "type": "invalid_request_error",
  "code": "invalid_field",
  "param": "name"
}

Some endpoints add their own fields next to these. Payment errors carry reason and dashboard_url, for example (billing).

#Status codes and types

#Common codes

New codes can appear at any time, so always keep a default branch.

#Platform errors

When Instagram, Google, Meta or another platform refuses a request, the response says which one and includes its payload untouched:

{
  "error": "Google rejected the ad: NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET",
  "type": "platform_error",
  "code": "platform_api_error",
  "platform": "google",
  "platformError": { "code": 3, "message": "Request contains an invalid argument." }
}

A platform 4xx usually means the input needs fixing. A 502 means the platform failed or timed out, and a retry often works.

#Publishing errors live on the post

A scheduled post fails later, long after your request returned 200. Those failures do not come back as an error response. Instead, the post ends with status: "failed" (no target published) or "partial" (some did), and each failed entry in platforms[] explains why:

{
  "platform": "instagram",
  "status": "failed",
  "errorMessage": "The aspect ratio of this video is not supported for reels.",
  "errorCategory": "user_content",
  "errorSource": "user"
}

errorSource tells you who has to act: user, platform or system. POST /v1/posts/{postId}/retry runs only the failed targets again. Subscribe to post.failed, post.partial and post.platform.failed to hear about these as they happen (post lifecycle).

#What to retry

#Request ids

Every response carries an X-Request-Id header. Log it with the error. Support can trace any request from that id (support).

You can send your own x-request-id (for example the id of your job) and Pozy uses it for that request, so your logs and Pozy's line up.

curl -i https://api.pozy.ai/v1/posts/6721a0c47b2e5f9d3a18c6e0 \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "x-request-id: 3e0f7a52-9b1c-4c6d-8f2e-5a7b9c1d3e4f"

#Handle errors in code

// A network error throws here: it is safe to retry with the same Idempotency-Key.
const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Hello", platforms: [] }),
});
if (!res.ok) {
  const body = await res.json();
  const requestId = res.headers.get("x-request-id");
  if (res.status === 429 || res.status >= 500) {
    // retry later, see "What to retry"
  } else if (body.type === "invalid_request_error") {
    console.error(`Fix ${body.param ?? "the request"}:`, body.error, body.details);
  } else {
    console.error(res.status, body.code, body.error, `request ${requestId}`);
  }
}

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"content": "Hello", "platforms": []},
    timeout=30,
)
if not resp.ok:
    body = resp.json()
    request_id = resp.headers.get("x-request-id")
    if resp.status_code == 429 or resp.status_code >= 500:
        pass  # retry later, see "What to retry"
    else:
        raise RuntimeError(f"{resp.status_code} {body.get('code')}: {body.get('error')} (request {request_id})")