Chyby a limity

Tvar chyby#

API v1 vracia pri chybe vhodný HTTP stav a telo:

{"error": {"code": "validation", "message": "definition.0.currency"}}

• code je stály strojový kód (tabuľka nižšie). Rozhodujte sa podľa neho a podľa HTTP stavu.
• message upresní pole alebo dôvod (napríklad email, name, version, status, scope). Nie je to text pre ľudí.
• params nesie podrobnosti: issues (problémy grafu automatizácie), expected a actual (počet príjemcov), current (verzia), reason, retryAfter.

API v3 kompatibilné so SmartEmailingom má vlastný tvar {"status": "error", "meta": [], "message": "..."}, pozrite Kompatibilita so SmartEmailingom.

HTTP stavy#

Kódy chýb#

conflict#

Význam: The change would break the state of the object. message: name (name taken), locked (a list bound to an e-shop), status (wrong state, e.g. editing a sent campaign), recipients (the audience changed more than 5 % since you counted it, params.expected and params.actual), version (stale baseVersion, params.current), confirm (saving a running automation needs confirmRunning: true), waiting (contacts wait in a node you remove, params.nodes), runs (deleting an automation that ran), trigger (no manual trigger), limit (too many objects).

Čo urobiť: Read the object again, then repeat with current data; for recipients count the audience again and send the new expectedRecipients.

count_mismatch#

Význam: expectedRecipients does not match the audience.

Čo urobiť: Count again with POST /campaigns/audience and send the new number.

csrf#

Význam: Browser session request without the CSRF header (never with an API key).

Čo urobiť: Send the API key in Authorization instead of cookies.

empty_segment#

Význam: The campaign audience has no recipient.

Čo urobiť: Change the audience.

expired#

Význam: The object is no longer available (an export file older than its retention).

Čo urobiť: Create it again (POST /exports).

forbidden#

Význam: The credentials are valid but not allowed here. message: tenant (another company in the path), scope (a read-only key on a write route), api_key (members, invitations and keys need a signed-in person), a module name (contacts, campaigns, content, settings, billing: the key's roles lack the level), read_only (support view).

Čo urobiť: Use the tenant id of the key (GET /api/v3/account-info), a key with scope full, or a key whose roles include the module (for example marketing_manager).

method_not_allowed#

Význam: The path exists but not with this HTTP method.

Čo urobiť: Check the method in this document.

not_found#

Význam: The object does not exist in this company (objects of other companies answer the same).

Čo urobiť: Check the id; list the objects first.

not_implemented#

Význam: The feature is not available yet.

Čo urobiť: Do not rely on it.

rate_limited#

Význam: Too many requests: the company's API limit, or the limit of one action (test e-mails, contact events, sign-in attempts). Retry-After says after how many seconds to retry.

Čo urobiť: Wait Retry-After seconds; spread requests (4 a second sustained).

recently_sent#

Význam: HTTP 423: the contact cannot be deleted yet, a campaign e-mail to it is queued or went out in the last 24 hours (SmartEmailing answers the same).

Čo urobiť: Delete it after 24 hours. A request to be forgotten (GDPR) uses POST /contacts/{id}/erase, which is never refused.

server#

Význam: Unexpected server error.

Čo urobiť: Retry later; the request may be repeated if it is safe to repeat.

suppression_locked#

Význam: The address is suppressed for another reason (bounce, complaint, unsubscribe), so the blacklist cannot be added or removed; params.reason names it.

Čo urobiť: Leave it: such suppressions protect the sender and are removed only one by one (DELETE /suppressions/{email}) when the reason is gone.

unauthorized#

Význam: No valid credentials: the API key is unknown, revoked, expired, idle for 180 days, its creator left the company, or the HTTP Basic user name is not an active member.

Čo urobiť: Check the key and the header (Authorization: Bearer pst_...). Create a new key in Nastavení › Datové zdroje › API klíče.

unavailable#

Význam: A service the action needs is not available (mail: the mail backend refused a test e-mail, data_key: encryption key for webhook passwords missing).

Čo urobiť: Retry later; tell support when it persists.

upstream#

Význam: An outside service failed (downloading a file by URL, the stock photo service); params.reason says why.

Čo urobiť: Check the URL or retry later.

validation#

Význam: A parameter or body field is missing, has the wrong type or an invalid value. message names it (email, definition.1.0.listId, graph ...), params may carry details such as params.issues of an automation graph or params.reason.

Čo urobiť: Fix the named field. For 415 contentType send Content-Type: application/json; for body send a JSON object.

Limity požiadaviek#

• Na firmu (všetky kľúče spolu): zásobník 2 500 požiadaviek doplňovaný 4 požiadavkami za sekundu a 100 000 požiadaviek za deň.
• Hlavičky každej odpovede: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unixový čas plného zásobníka).
• Po prekročení 429 rate_limited (v message názov zásobníka per-second alebo daily-limit) a Retry-After v sekundách.

Limity akcií#

Ako reagovať#