API-и паёмрасон

Ҳар чизе, ки панел бо аккаунти пайвастшудаи Instagram, WhatsApp ё Telegram карда метавонад, тавассути REST — як калид, як шакли посух, фасл ба фасл.

Хатоҳо ва маҳдудияти дархостҳо

Формати хато, ҳар рамзи хато бо ҳолати HTTP ва тарзи кори маҳдудиятҳо.

Error shape

Failures always use this shape. Branch on code, never on the message text. details (optional) carries validation errors per field.

{
  "success": false,
  "error": { "code": "DEVICE_OFFLINE", "message": "No available device is currently online.", "details": {} }
}

Error codes

401INVALID_API_KEYThe API key is missing or invalid.

401API_KEY_EXPIREDThis API key has expired.

401API_KEY_REVOKEDThis API key has been revoked.

403INSUFFICIENT_SCOPEThis API key does not have the required scope.

403ORGANIZATION_SUSPENDEDThis account is suspended.

401INVALID_CREDENTIALSThose credentials do not match our records.

403ACCOUNT_SUSPENDEDThis account is suspended. Contact support.

422TWO_FACTOR_CODE_INVALIDThe code is wrong.

422CHALLENGE_EXPIREDThis sign-in attempt has expired. Start again.

422APPLE_NOT_LINKEDNo ChatVendor account uses this Apple ID yet. Sign in with your e-mail once, then link Apple ID under Security.

401UNAUTHENTICATEDThe session is missing or has expired. Sign in again.

403FORBIDDENYou do not have access to this.

404NOT_FOUNDThe requested resource was not found.

400REQUEST_FAILEDThe request could not be completed.

422VALIDATION_FAILEDThe request contains invalid parameters.

422INVALID_PHONE_NUMBERThe recipient phone number could not be parsed.

422MESSAGE_TOO_LONGThe message body exceeds the maximum length.

404MESSAGE_NOT_FOUNDNo message matches that identifier.

404BATCH_NOT_FOUNDNo batch matches that identifier.

404DEVICE_NOT_FOUNDNo device matches that identifier.

404WEBHOOK_NOT_FOUNDNo webhook endpoint matches that identifier.

409DEVICE_OFFLINENo available device is currently online.

409DEVICE_DISABLEDThe selected device is disabled.

409SIM_UNAVAILABLEThe selected SIM card is not available.

409SMS_PERMISSION_MISSINGThe device has not granted SMS permission.

422MESSAGE_NOT_CANCELLABLEThis message can no longer be cancelled.

429RATE_LIMIT_EXCEEDEDRate limit exceeded. Retry after the indicated delay.

402ENTITLEMENT_EXCEEDEDThis action exceeds your plan limits.

422IDEMPOTENCY_KEY_REUSEDThis idempotency key was already used with a different request body.

409IDEMPOTENT_REQUEST_IN_PROGRESSA request with this idempotency key is still in progress.

422INVALID_PAIRING_CODEThe pairing code is invalid.

422PAIRING_CODE_EXPIREDThe pairing code has expired.

500INTERNAL_ERRORAn unexpected error occurred.

402PLAN_REQUIREDMessenger API access is not included in the current plan.

404CHANNEL_NOT_FOUNDNo channel matches that identifier.

409CHANNEL_NOT_CONNECTEDThe channel is not connected.

502CONNECTOR_ERRORThe channel connector did not respond.

429FLOOD_WAITThe messenger asked us to slow down. Retry after the indicated delay.

422CHANNEL_REQUEST_FAILEDThe messenger rejected the request.

403CHECKOUT_UNAVAILABLEPlan changes are not available in this app.

403BILLING_OWNER_ONLYOnly the workspace owner can change the plan.

422BILLING_COUNTRY_REQUIREDChoose the billing country first.

409BILLING_COUNTRY_LOCKEDThe billing country can only be changed by support.

422PLAN_NOT_PURCHASABLEThis plan cannot be bought right now.

422PAYMENT_PROVIDER_UNAVAILABLEThis payment method is not available right now.

409PRICE_CHANGEDThe price has changed. Check the new total.

409CHECKOUT_IN_PROGRESSA payment is already being created. Try again in a moment.

502PAYMENT_PROVIDER_ERRORThe payment service did not respond. Try again.

404PAYMENT_NOT_FOUNDPayment not found.

Rate limits

Limits are layered: per API key, per workspace, per device and per SIM (the per-SIM limit protects the physical card from a runaway loop). Telegram adds its own flood limits: a 429 FLOOD_WAIT tells you how many seconds to wait. Every 429 carries Retry-After and X-RateLimit-* headers.