API Response

HTTP status codes and response format for the Messaging API

All Plivo API endpoints return a response in JSON format. An api_id in each response uniquely identifies each request.

---

​

Response Format

Every API response includes:

• api_id: Unique identifier for the request
• Resource data or error details
• HTTP status code

​

Success Response

{
  "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196",
  "message": "message(s) queued",
  "message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"]
}

---

​

HTTP Status Codes

Code	Description
200	Request has been executed successfully
201	Resource created
202	Resource changed
204	Resource deleted
400	A parameter is missing or is invalid
401	Authentication failed
404	Resource cannot be found
405	HTTP method is not allowed
429	Rate limit exceeded - too many requests
500	Server error

---

​

Error Responses

When a request fails, the response includes an error object:

​

Error Response Example

{
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
  "error": "not found"
}

​

Common Errors

Status	Error	Description
400	invalid_parameter	A required parameter is missing or has an invalid value
401	authentication_failed	Invalid Auth ID or Auth Token
404	not_found	The requested resource does not exist
429	rate_limit_exceeded	Too many requests in a given time period

---

​

Pagination Response

List endpoints return paginated responses with metadata:

​

Paginated Response Example

{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "meta": {
    "limit": 20,
    "next": "/v1/Account/{auth_id}/Message/?limit=20&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 45
  },
  "objects": [
    {
      "message_uuid": "...",
      "...": "..."
    }
  ]
}

​

Meta Fields

Field	Description
limit	Number of results per page
offset	Number of records skipped
total_count	Total number of matching records
next	URL for the next page of results (null if no more)
previous	URL for the previous page of results (null if first page)