Getting started

Errors & retries

Handle one structured error envelope, retry only when told, and preserve request IDs for support.

One error shape

Every API error returns an error object with a stable code, human-readable message, platform when relevant, retryability, optional details, and request ID.

Example errorPostGate API

{
  "error": {
    "code": "platform_transient",
    "message": "Instagram is temporarily unavailable.",
    "platform": "instagram",
    "retryable": true,
    "details": {},
    "request_id": "req_01JXYZ"
  }
}

Retry by signal, not by status alone

Retry only when retryable is true. Reuse the same Idempotency-Key for a logical post and apply exponential backoff with jitter. PostGate already retries provider delivery internally; client retries are for API transport and acceptance failures.

Do not recreate failed targets automatically

Inspect target evidence first. Content rejection and reconnect errors need a change or customer action, not more identical requests.

Act on stable codes

media_invalid needs a different asset. profile_disconnected needs reconnection. platform_not_configured means the provider is unavailable in this workspace. platform_content_rejected needs different content. rate_limited and platform_transient can be retryable.

Pagination is predictable

List endpoints use one-based page and per_page up to 100 where pagination applies. The response includes page, per_page, total, and total_pages.

Keep request IDs

Every response includes X-Request-Id. Store it with failed calls and include it in support requests so an API request can be correlated with delivery evidence.