Skip to content
UGC API
Get API key

Errors

All errors use the same JSON shape, whether they come back from a request or appear in a post result or webhook. Branch on code, show message to people.

Updated

Format

json
{
  "error": {
    "code": "invalid_request",
    "message": "media must be an array of URLs."
  }
}

code is stable and safe to branch on. message is for humans and may change. In post results and post.failed webhooks, the same { code, message } object appears as error.

Codes

CodeHTTPMeaningWhat to do
unauthorized401Missing, malformed or revoked API key.Check the Authorization: Bearer ugc_live_... header. See authentication.
insufficient_credits402Not enough credits for the results this request would create.Buy a pack in the dashboard. See pricing and credits.
invalid_request400A field is missing, has the wrong type, or the format isn't supported on a platform.Read the message and fix the field.
account_not_found404An account ID doesn't exist, was disconnected, or isn't yours.List accounts with GET /v1/accounts, reconnect if needed.
media_unreachable422A media URL couldn't be downloaded.Make the URL public and direct, or upload with POST /v1/media.
platform_rejected422The platform refused the content or request. The message carries the platform's reason.Fix the content or account setting the message names.
rate_limited429Too many requests to our API, or a platform limit was hit.Wait and retry with backoff.

Request errors vs result errors

  • Request errors come back right away with an HTTP status. Nothing was created.
  • Result errors happen later, when a platform processes a scheduled post. The request returned 200, and the failed result has status: 'failed' and an error. You also get a post.failed webhook.

Common platform_rejected reasons

PlatformTypical reason
TikTokCreator's daily posting cap reached; privacy level not allowed for the account; video too long for the creator.
InstagramAccount isn't Business or Creator; daily publishing limit reached; unsupported media.
FacebookReel outside 3 to 90 seconds; Page permission removed.
YouTubeUpload quota reached; channel can't upload.

Per-platform caps are in limits.

Handling errors in code

javascript
const res = await fetch("https://ugcapi.dev/v1/posts", { method: "POST", headers, body });
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "insufficient_credits": return showTopUp();
    case "rate_limited": return retryLater();
    case "account_not_found": return askToReconnect();
    default: throw new Error(error.code + ": " + error.message);
  }
}

Retry only rate_limited and network errors automatically. Other codes need a change before a retry can succeed. For webhook-side handling, see webhooks for social publishing.

FAQ

Am I charged for failed posts?

No. Credits are used only for results that publish.

Should I retry platform_rejected errors?

Not unchanged. Read the message, fix the cause, then create a new post.

Will new error codes be added?

Possibly. Treat unknown codes like a generic failure and show the message.

Related

DocsLimitsDocsWebhooksDocsAuthenticationGuidesWebhooks for social publishing