Reference
Errors
Every failure has the same shape: an HTTP status, a machine-readable error code, and a sentence written for a person rather than a log.
{
"error": "insufficient_credits",
"message": "There are not enough credits for this. Top up in Personade under Billing, or reduce the number of people."
}Codes
| Code | Status | Retry? | Meaning |
|---|---|---|---|
unauthorized | 401 | No | The key is missing, malformed or revoked. |
forbidden | 403 | No | This key may read but not write. Make one that can build campaigns. |
not_found | 404 | No | No campaign or recording with that id, or it belongs to another workspace. Deliberately the same answer for both. |
bad_input | 400 | No | A field is missing or the wrong type. The message says which. |
insufficient_credits | 402 | No | Not enough credits. Top up, or send fewer people. |
past_due | 402 | No | The last payment failed, so nothing paid can run until the card is fixed. |
no_voice | 409 | No | The campaign's recording has no usable voice yet, so the videos would fail. |
needs_refilm | 409 | No | The recording has no name in it to personalize. It has to be filmed again. |
not_ready | 409 | No | There is nobody left to make a video for. Add people first. |
campaign_busy | 409 | Yes | This campaign is already generating, so it cannot be changed right now. Wait for it to finish. |
cap_reached | 429 | No | This key has spent its daily credit allowance. It resets at midnight UTC, or raise it on a new key. |
rate_limited | 429 | Yes | More than 120 requests in a minute on this key. Wait and try again. |
internal | 500 | Yes | Our fault. Retry in a moment, and tell us if it keeps happening. |
Retrying
Only the three marked yes are worth retrying, and those with a wait between attempts. Everything else is a 4xx that describes something a retry cannot change: an empty balance does not fill up because you asked twice.
Idempotency
There is no idempotency key on this API. Whether a retry is safe depends on the endpoint, so the three that matter are worth stating plainly.
| Endpoint | Safe to retry? | Why |
|---|---|---|
POST /leads | Yes | People are matched on what identifies them: an email, a profile link, or a name and company together. Somebody already in the campaign is skipped, not added again. A row carrying none of those cannot be matched and would be added twice. |
POST /campaigns | No | A retry creates a second campaign with the same name. Harmless but confusing. List first if you are unsure it landed. |
POST /generate | No | This charges. A campaign already generating answers 409 campaign_busy rather than charging twice, but once it settles a second call charges for anyone still pending. Poll the status instead of retrying. |
A 404 on every endpoint
If every path answers 404 not_found, including ones you know exist, the API is switched off for the whole site rather than your URL being wrong. That is deliberate: a disabled surface should not advertise that it is merely switched off. Email support@personade.com.
Start building
Still stuck?
Send us the error code and roughly when it happened. We can see the request on our side.