GuidesAPI EndpointsKnowledge BaseSupportTalkdesk WebsiteMarketplaceDiscussionsDevelopers Blog
Guides

Standard Response Format

Suggest Edits

Standard Response Format

To ensure consistency across the platform, all Advanced Dialer APIs utilize a standardized JSON envelope for every response. This structure allows developers to handle successes and errors using a uniform logic pattern.

Response Structure

Every API response contains three root-level properties:

FieldTypeDescription
statusCodeintegerA numeric code indicating the result of the operation.
messagestringA human-readable description of the result or specific error details.
payloadvaryThe actual data requested (Object, Array, or Null).

Example Envelope

{
  "statusCode": 0,
  "message": "Operation completed successfully",
  "payload": {
    "id": 1001,
    "status": "Active"
  }
}

Status Codes Reference

The following table defines the specific status codes returned by the Advanced Dialer gateway.

CodeStatusDescription
0SuccessThe request was processed successfully.
1WarningThe request succeeded, but with non-critical issues.
2ErrorA general processing error occurred.
3Authentication FailedInvalid or missing API keys/credentials.
4Authorization FailedThe authenticated user lacks permission for this resource.
5Validation ErrorThe request body or parameters failed schema validation.
6Not FoundThe requested resource (Agent, Campaign, etc.) does not exist.
8System ErrorAn internal server error occurred.
9TimeoutThe request took too long to process.
10Rate LimitedToo many requests have been sent in a given timeframe.

🚧

Best Practice

Always check the statusCode value before attempting to parse the payload to ensure your application handles errors gracefully.

Troubleshooting Common Errors

When an API request does not return statusCode: 0, refer to this guide to resolve the most common integration hurdles.

🔑 Authentication & Authorization (Codes 3 & 4)

Errors in this category usually relate to your API Key or the specific permissions assigned to that key.

CodeStatusCommon CausesRecommended Action
3Authentication FailedMissing or mistyped Ocp-Apim-Subscription-Key.Verify the key is present in the header and exactly matches your dashboard.
4Authorization FailedThe API Key is valid, but doesn't have access to the specific "Product" (e.g., Dialer vs. CRM).Check your subscription settings to ensure the key is associated with the correct API Product.

📘

Header Check

Ensure your keys are passed as headers, not as query parameters, unless specifically noted for a legacy endpoint.

🚦 Rate Limiting (Code 10)

To ensure system stability, the Advanced Dialer API enforces rate limits. If you receive Code 10, your application is sending requests too frequently.

Recommended Handling: "Exponential Backoff"

If you encounter a rate limit, do not immediately retry the request. Instead:

  1. Wait 1 second.
  2. Retry the request.
  3. If it fails again, wait 2 seconds, then 4 seconds, and so on.
{
  "statusCode": 10,
  "message": "Rate limit exceeded. Please try again in 30 seconds.",
  "payload": null
}

❌ Validation & Not Found (Codes 5 & 6)

These errors are typically "Client Errors," meaning the request itself needs to be modified.

  • Code 5 (Validation Error): Usually occurs during a POST or PUT. Check that your JSON body matches the required data types (e.g., sending a string where an integer is expected).
  • Code 6 (Not Found): Double-check your IDs. For example, if you are querying /api/agent/1001, ensure that Agent 1001 actually exists in your specific tenant/prefix.

⚙️ System Errors (Code 8)

If you receive a Code 8, the issue is on the server side.

  1. Check the [Talkdesk Status Page] to see if there is an active incident.
  2. If the status is "Green," wait 60 seconds and try once more.
  3. If the error persists, contact support with the eventId if provided in the response message.

Updated about 3 hours ago