HTTP methods for API interactions

To build secure and reliable integrations, you must understand REST API methods. Each HTTP method has a specific purpose. Correct usage ensures predictable behavior and proper error handling for your app.

HTTP methods overview

Twilio's REST API uses standard HTTP methods to perform operations on resources. Each method maps to a specific action that determines how your request is processed:

Purpose	HTTP method	Action	Never use
Retrieve collection	`GET`	Retrieves a collection of resources of a specific type.
Retrieve resources	`GET`	Retrieves a specific resource using its SID.
Create collection	`POST`	Creates a new resource by sending data to a collection endpoint.
Update resources	`POST`	Updates an existing resource using its SID.	`GET`,`PUT`,`PATCH`
Remove resources	`DELETE`	Deletes an existing resource.

The following examples demonstrate each HTTP method. Select your method to see the request structure:

GET: List resourcesGET: Retrieve a resourcePOST: Create a resourcePOST: Update a resourceDELETE: Delete a resource

Retrieve a collection of resources of a specific type

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function listMessage() {
14  const messages = await client.messages.list({ limit: 20 });
15
16  messages.forEach((m) => console.log(m.end));
17}
18
19listMessage();

Response

1{
2  "end": 1,
3  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
4  "next_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
5  "page": 0,
6  "page_size": 2,
7  "previous_page_uri": null,
8  "messages": [
9    {
10      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
11      "api_version": "2010-04-01",
12      "body": "testing",
13      "date_created": "Fri, 24 May 2019 17:44:46 +0000",
14      "date_sent": "Fri, 24 May 2019 17:44:50 +0000",
15      "date_updated": "Fri, 24 May 2019 17:44:50 +0000",
16      "direction": "outbound-api",
17      "error_code": null,
18      "error_message": null,
19      "from": "+12019235161",
20      "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21      "num_media": "0",
22      "num_segments": "1",
23      "price": "-0.00750",
24      "price_unit": "USD",
25      "sid": "SMded05904ccb347238880ca9264e8fe1c",
26      "status": "sent",
27      "subresource_uris": {
28        "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
29        "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
30      },
31      "to": "+18182008801",
32      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
33    },
34    {
35      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
36      "api_version": "2010-04-01",
37      "body": "look mom I have media!",
38      "date_created": "Fri, 24 May 2019 17:44:46 +0000",
39      "date_sent": "Fri, 24 May 2019 17:44:49 +0000",
40      "date_updated": "Fri, 24 May 2019 17:44:49 +0000",
41      "direction": "inbound",
42      "error_code": 30004,
43      "error_message": "Message blocked",
44      "from": "+12019235161",
45      "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
46      "num_media": "3",
47      "num_segments": "1",
48      "price": "-0.00750",
49      "price_unit": "USD",
50      "sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
51      "status": "received",
52      "subresource_uris": {
53        "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
54        "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
55      },
56      "to": "+18182008801",
57      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
58    }
59  ],
60  "start": 0,
61  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
62}

Retrieve a specific resource by its SID

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchMessage() {
14  const message = await client
15    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
16    .fetch();
17
18  console.log(message.body);
19}
20
21fetchMessage();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "testing",
5  "date_created": "Fri, 24 May 2019 17:18:27 +0000",
6  "date_sent": "Fri, 24 May 2019 17:18:28 +0000",
7  "date_updated": "Fri, 24 May 2019 17:18:28 +0000",
8  "direction": "outbound-api",
9  "error_code": 30007,
10  "error_message": "Carrier violation",
11  "from": "+12019235161",
12  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "num_media": "0",
14  "num_segments": "1",
15  "price": "-0.00750",
16  "price_unit": "USD",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "sent",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
21    "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
22  },
23  "to": "+18182008801",
24  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
25}

Create a new resource by sending data to a collection endpoint

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createMessage() {
14  const message = await client.messages.create({
15    body: "Hello World",
16    from: "+0987654321",
17    to: "+1234567890",
18  });
19
20  console.log(message.body);
21}
22
23createMessage();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "Hello World",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "+0987654321",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "+1234567890",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

Update an existing resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function updateMessage() {
14  const message = await client
15    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
16    .update({ body: "Updated message" });
17
18  console.log(message.body);
19}
20
21updateMessage();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "Updated message",
5  "date_created": "Fri, 24 May 2019 17:18:27 +0000",
6  "date_sent": "Fri, 24 May 2019 17:18:28 +0000",
7  "date_updated": "Fri, 24 May 2019 17:18:28 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "+12019235161",
12  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "num_media": "0",
14  "num_segments": "1",
15  "price": null,
16  "price_unit": "USD",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "sent",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
21    "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
22  },
23  "to": "+18182008801",
24  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
25}

Delete an existing resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function deleteMessage() {
14  await client.messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
15}
16
17deleteMessage();

HTTP status codes

Twilio returns standardized HTTP status codes that indicate the success or failure of your request. Understanding these codes helps you implement proper error handling and detect security issues:

Success status codes (2xx)

Code	Error	Reason
200	OK	Request succeeded; response body contains the resource.
201	Created	Resource creation succeeded. The response body contains the new resource.
204	No Content	Request succeeded (typically for `DELETE`) and it doesn't return a response body.

Client error status codes (4xx)

Code	Error	Reason
`400`	Bad Request	Malformed request syntax or invalid parameters
`401`	Unauthorized	Missing, invalid, or expired credentials
`403`	Forbidden	Credentials are valid but lack permission for this action
`404`	Not Found	Resource does not exist or belongs to a different account
`429`	Too Many Requests	Rate limit or concurrency limit exceeded

Server error status codes (5xx)

Code	Error	Reason
`500`	Internal Server Error	Server error; retry with exponential backoff
`503`	Service Unavailable	Temporary service disruption; retry with exponential backoff

Understanding status codes for security

HTTP status codes provide critical information for detecting security issues and API problems.

4xx errors and credential security

Certain responses indicate authentication or authorization problems: 401 (Unauthorized) and 403 (Forbidden).

Code	Error	Reason	Security implication	Remedy
`401`	Unauthorized	Missing, invalid, or expired credentials	Sudden spikes in `401` errors may indicate credential compromise or token expiration issues.	Verify credentials remain correct and haven't expired; rotate if suspicious.
`403`	Forbidden	Credentials lack permission for the requested action	Access to endpoints your integration doesn't normally use may indicate unauthorized changes to access policies.	Verify API key scopes and permissions; investigate unusual access patterns.

Rate limiting and abuse detection

429 Too Many Requests indicates you've exceeded rate limits or concurrency limits. This may indicate legitimate spike in usage or an unauthorized user making rapid requests.

Implement exponential backoff to retry after the rate limit resets.
Monitor for sudden 429 spikes that could indicate compromise or abuse.

5xx errors and service issues

500 and 503 errors indicate server-side issues.

Implement retry logic with exponential backoff. Don't retry indefinitely.
5xx errors should be rare; frequent 5xx responses may indicate a systemic problem.
Distinguish between transient failures, where you would retry, and systemic problems, where you escalate to Twilio Support.

Monitoring and alerting strategy

Set up monitoring and alerts for these security-relevant patterns:

Sudden spikes in 401 or 403 responses from possible credential compromise or permission changes
Repeated 429 responses from rate limiting, possible abuse, or Denial of Service (DoS)
Access to new endpoints or resources not previously used
Requests with unusual geographic origin or timing patterns
Mixing of expected and unexpected HTTP methods like unexpected DELETE requests

Best practices for API interactions

Implement these practices when making HTTP requests to Twilio APIs:

HTTP method usage

To perform certain actions, use the following HTTP methods with the Twilio REST API:

Purpose	HTTP method	Never use
Retrieve resources	`GET`
Create resources	`POST`
Update resources	`POST`	`GET`, `PUT`, `PATCH`
Remove resources	`DELETE`

Error handling and retries

Implement proper error handling for all status codes, not just successful responses.
Implement exponential backoff when retrying errors (5xx, occasional 429)..
Log all error responses with status code, timestamp, and endpoint for audit trails.
Monitor specific status codes to detect security or operational issues.
Don't retry 4xx errors indefinitely; investigate the root cause.

Security-specific practices

Monitor 401 and 403 responses for patterns that could indicate compromise.
Alert on sudden changes in request patterns or unusual geographic origins.
Implement rate limiting on your app side to prevent hitting Twilio limits.
Test error handling during development; don't skip error scenarios.

Next steps

Secure your API interactions and error handling:

Defense-in-depth strategy: comprehensive security approach including monitoring
Incident response: responding to detected security issues
Webhook security: validating inbound requests and responses
API in transit security: encryption and secure communication
Twilio REST API reference: detailed API documentation