Chyby a limity

Tvar chyby#

API v1 vrací při chybě vhodný HTTP stav a tělo:

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

• code je stálý strojový kód (tabulka níže). Rozhodujte se podle něj a podle HTTP stavu.
• message upřesní pole nebo důvod (například email, name, version, status, scope). Není to text pro lidi.
• params nese podrobnosti: issues (problémy grafu automatizace), expected a actual (počet příjemců), current (verze), reason, retryAfter.

API v3 kompatibilní se SmartEmailingem má vlastní tvar {"status": "error", "meta": [], "message": "..."}, viz Kompatibilita se SmartEmailingem.

HTTP stavy#

Kódy chyb#

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).

Co udělat: 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.

Co udělat: 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).

Co udělat: Send the API key in Authorization instead of cookies.

empty_segment#

Význam: The campaign audience has no recipient.

Co udělat: Change the audience.

expired#

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

Co udělat: 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).

Co udělat: 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.

Co udělat: 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).

Co udělat: Check the id; list the objects first.

not_implemented#

Význam: The feature is not available yet.

Co udělat: 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.

Co udělat: 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).

Co udělat: 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.

Co udělat: 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.

Co udělat: 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.

Co udělat: 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).

Co udělat: 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.

Co udělat: 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.

Co udělat: Fix the named field. For 415 contentType send Content-Type: application/json; for body send a JSON object.

Limity požadavků#

• Na firmu (všechny klíče dohromady): zásobník 2 500 požadavků doplňovaný 4 požadavky za sekundu a 100 000 požadavků za den.
• Hlavičky každé odpovědi: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unixový čas plného zásobníku).
• Po překročení 429 rate_limited (v message název zásobníku per-second nebo daily-limit) a Retry-After v sekundách.

Limity akcí#

Jak reagovat#