Skip to content

Errors & idempotency ​

The error shape ​

Every error is the same JSON, { code, message, …fields }: a machine-readable code naming the error, a human message saying what went wrong and how to fix it, and the fields that pin down the specifics as data.

An error’s body
{
  "code": "PlatformNotConnectedError",
  "message": "This brand has no active YouTube connection — connect YouTube from the dashboard, then retry.",
  "platform": "youtube"
}

Branch on code, never on the message: the wording can change. Show the message to a person — it names the specifics on its own — and read the fields when your code needs them. Every error, with its fields, is in the API reference.

Status codes ​

StatusMeaning
400the request body or parameters failed validation (InvalidRequestError; message says which field and why), or storage refused an upload’s part list (UploadRejectedError — the upload stays open: complete it again with the right parts)
401missing or invalid credentials (UnauthorizedError)
402the team’s plan has no room for it: a new video past the Free plan’s monthly limit (VideoLimitReachedError), or a brand past the plan’s brand limit (BrandLimitReachedError). Both carry the plan and its limit; message says how to upgrade
403authenticated, but not allowed: no team yet (NoTeamError), or the API key’s scope doesn’t cover this (InsufficientScopeError, BrandOutOfScopeError)
404the resource doesn’t exist, or isn’t visible to this caller — including a {brandId} that isn’t one of your brands (BrandNotFoundError)
409a conflict: an idempotency key was reused, the brand is archived (BrandArchivedError), or the resource is in a non-retryable state
422a referenced resource (asset, cover, caption, platform) is invalid for the operation, or a platform would refuse the video (VideoNotAcceptedError, whose refusals list every limit the video breaks: see Shape and length)
429the API key is throttled (RateLimitedError)
500an unexpected fault on our side (InternalServerError), or we couldn’t queue the publish (DispatchSendFailedError: its publicationId exists, and the targets we couldn’t send are failed; read it and retry them)

A 422 is the one to read closely: it carries which reference was wrong. Publishing surfaces AssetNotVideoError, the Cover* and Caption* errors, PlatformNotConnectedError, DuplicatePlatformError, AlreadyTargetedError, PlatformMessageTooLongError, PlatformMessageCharactersError and PublishAtInPastError, each naming the offending asset or platform in its message and its fields, so you can fix the target rather than guess.

Idempotency ​

The write that matters, POST /brands/{brandId}/publications, accepts an Idempotency-Key header. Send a unique key per logical publish, and a retried request with the same key answers with the publication the first one created instead of publishing twice. The key is bound in the same write that creates the publication, so even a first request that then failed (500 DispatchSendFailedError, or a 500 whose answer was lost) is replayed. A request refused before it created anything stores nothing, so retrying it with the same key runs it again — a request rejected for a bad body doesn’t burn its key: fix it and retry with the same one.

Send the key with the publish request, under the brand it publishes as (Brands lists their IDs):

curl: an idempotent publish
curl -X POST "$API/brands/$BRAND/publications" \
  -H "Authorization: Bearer $SK" -H "Idempotency-Key: 7c3f…" \
  -H "Content-Type: application/json" -d '{ … }'
  • Same key, same body → 201 with the answer as the publication was created: its id, and every target as it was then (pending). For the publication’s current state, read it with GET /brands/{brandId}/publications/{id}. No second publish.
  • Same key, different body → 409 IdempotencyKeyReusedError. A key is bound to the request it first saw.
  • Same key, still in flight → 409 RequestInProgressError. Retry it a few times over a minute: the first request either answers or frees the key, and the retry replays or runs. If it persists, the first request ended without an answer and may have made its publication: look for it in the ledger (GET /brands/{brandId}/publications). Don’t send the publish under a new key, or wait out the key’s 24 hours, to recover — either can publish the video a second time.

A key belongs to your team (another team’s key never collides with yours) and is kept for 24 hours: a retry after that runs the request again, so it is no way to recover a lost answer. Keys aren’t required. A keyless write simply runs every time, so generate a key (a UUID is ideal) whenever a retry must be safe.

When a publish fails after it was made ​

500 DispatchSendFailedError means the publication exists but some of its targets couldn’t be queued. Its publicationId names it (a replay with the same key gives the same id):

  1. Read it: GET /brands/{brandId}/publications/{publicationId}. A target that went out is processing or later; one we couldn’t send is failed, with failure.kind internal.
  2. Retry each failed target by id: POST /brands/{brandId}/publications/{publicationId}/targets/{targetId}/retry. It goes at once; if it answers 409 SettlementPendingError, the failure is still being recorded: try again in a few minutes.

Don’t send the publish again under a new key: the targets that went out would post twice.

Generate the key — don’t derive it from your content. Mint a fresh UUID when you start a publish, keep it, and resend that same value only if you have to retry the same call. A key derived from the request body or the video (a hash of either) looks idempotent but isn’t: a re-upload produces a different asset, so the body changes and the derived key collides across two genuinely distinct publishes (409 IdempotencyKeyReusedError) — while a real retry needs the value to stay identical, which a fresh hash won’t give you either.

The API is the product; the dashboard is its best-known client.