{ "openapi": "3.0.1", "info": { "title": "Twilio - Insights", "description": "The Twilio Insights v3 API provides semantic query access to Conversations\nanalytics data. Resources include synchronous Query, Metadata, and asynchronous\nQueryJobs for long-running queries.\n", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio Support", "url": "https://support.twilio.com", "email": "support@twilio.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.1.0", "x-twilio": { "apiStandards": "v1.0" } }, "servers": [ { "url": "https://insights.twilio.com" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "tags": [ { "name": "TwilioInsights", "description": "Twilio Insights synchronous Query and Metadata resources." }, { "name": "TwilioInsightsAsync", "description": "Twilio Insights asynchronous QueryJobs resource (long-running query operations)." } ], "components": { "securitySchemes": { "basic_apikey_or_accountsid": { "scheme": "basic", "type": "http", "description": "This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing." } }, "responses": { "UnprocessableContentError": { "description": "Unprocessable content (idempotency key payload mismatch)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "BadRequestError": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "UnauthorizedError": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "ForbiddenError": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "RateLimitError": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "headers": { "X-Rate-Limit-Limit": { "schema": { "type": "string" } }, "X-Rate-Limit-Remaining": { "schema": { "type": "string" } }, "X-Rate-Limit-Config": { "schema": { "type": "string" } } }, "schemas": { "PaginationMeta": { "type": "object", "description": "The pagination metadata containing navigation tokens and result information.\nBy convention, this schema should be added to the response payload's\n'meta' attribute.\n", "required": [ "key", "pageSize" ], "properties": { "key": { "type": "string", "nullable": false, "description": "The key of the list property contains the actual data items.\nThis enables programmatic iteration over paginated results.\n", "example": "items" }, "pageSize": { "type": "integer", "nullable": false, "description": "The actual number of items returned in this response.\nMay be less than the requested pageSize for the last page.\n", "example": 20 }, "previousToken": { "type": "string", "nullable": true, "description": "Token to fetch the previous page of results.\nOnly included if there is a previous page, otherwise omitted.\n", "example": "eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0=" }, "nextToken": { "type": "string", "nullable": true, "description": "Token to fetch the next page of results.\nOnly included if there is a next page, otherwise omitted.\n", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } }, "QueryDefinition": { "type": "object", "description": "Structured query definition that specifies what data to retrieve and how to filter, group, and order it", "properties": { "measures": { "type": "array", "description": "Array of measures to retrieve, representing quantitative values or metrics to be calculated", "items": { "type": "string" }, "example": [ "OperatorResult.Count" ] }, "dimensions": { "type": "array", "description": "Array of dimensions to retrieve, representing categorical attributes for grouping and organizing data", "items": { "type": "string" }, "example": [ "DateCreated", "OperatorResults" ] }, "filters": { "type": "array", "description": "Nested filter conditions. Always use `op` and `expressions`.", "items": { "type": "object", "required": [ "expressions" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "AND" }, "expressions": { "type": "array", "items": { "type": "object", "required": [ "op", "field" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "IN" }, "field": { "type": "string", "example": "OperatorResult.Value" }, "values": { "type": "array", "items": { "type": "string" }, "example": [ "positive", "negative" ] } } } } } } }, "orderBy": { "type": "array", "description": "Specifications for sorting the query results by specific fields in ascending or descending order", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Dimension or measure to order by", "example": "OperatorResults.CreatedDate" }, "direction": { "type": "string", "description": "Sort order direction, ascending or descending", "enum": [ "ASC", "DESC" ], "example": "DESC" } } } } } }, "InsightsQueryRequest": { "type": "object", "required": [ "query" ], "properties": { "domain": { "type": "string", "example": "Conversations", "description": "The business domain to execute the query against" }, "query": { "$ref": "#/components/schemas/QueryDefinition" } } }, "InsightsQueryResponse": { "type": "object", "properties": { "domain": { "type": "string", "example": "Insights", "description": "Indicates the business domain the query was executed against" }, "items": { "type": "array", "description": "Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions.", "items": { "type": "object", "description": "Query result object with dynamic properties based on requested measures and dimensions.", "additionalProperties": { "description": "Dynamic property values based on requested measures and dimensions." } }, "example": [ { "Id": "conv1", "Languages": [ "en" ], "Channels": [ "voice" ], "OperatorResult.Value": "positive" }, { "Id": "conv2", "Languages": [ "en", "es" ], "Channels": [ "chat" ], "OperatorResult.Value": "negative" } ] }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "InsightsMetadataResponse": { "type": "object", "description": "Response containing metadata about available cubes, measures, and dimensions for a domain", "properties": { "domain": { "type": "string", "example": "Insights", "description": "The business domain name for which metadata is being provided" }, "cubes": { "type": "array", "description": "List of data cubes available in the domain, each containing measures and dimensions", "items": { "type": "object", "required": [ "name", "measures", "dimensions" ], "properties": { "name": { "type": "string", "description": "Name of the cube, used as a reference in queries" }, "description": { "type": "string", "description": "Human-readable description of what the cube represents" }, "measures": { "type": "array", "description": "List of measures available in the cube, representing quantitative values that can be aggregated", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this measure in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this measure represents" }, "type": { "type": "string", "description": "Type of the measure" }, "aggregation": { "type": "string", "description": "Aggregation type for the measure (e.g., sum, count, average)" } } } }, "dimensions": { "type": "array", "description": "List of dimensions available in the cube, representing categorical attributes for grouping data", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this dimension in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this dimension represents" }, "type": { "type": "string", "description": "Data type of the dimension (e.g., string, number, boolean, date)" } } } } } } } } }, "LongRunningOperationStatus": { "description": "The valid status values for long-running operations.", "type": "string", "enum": [ "PENDING", "RUNNING", "CANCELLED", "COMPLETED", "FAILED" ] }, "OperationError": { "description": "The error details for a failed operation, embedded inside a 200 OK operation envelope.", "type": "object", "required": [ "code", "message", "httpStatusCode" ], "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32", "example": 50001 }, "message": { "description": "A human readable error message", "type": "string", "example": "Query execution timeout exceeded" }, "httpStatusCode": { "description": "HTTP status code that would have been returned for a synchronous failure", "type": "integer", "format": "int32", "example": 504 }, "detail": { "description": "Additional context about the failure", "type": "string", "nullable": true, "example": "ClickHouse query exceeded the 120s execution limit." } } }, "QueryJobSubmitResponse": { "description": "The initial 202 response for an async query submission.\nConforms to LongRunningOperation202Response from Twilio API Standards.\n", "type": "object", "additionalProperties": true, "required": [ "operationId", "status", "statusUrl", "createdAt" ], "properties": { "operationId": { "type": "string", "format": "Proc_JobTtid", "description": "The unique identifier for the asynchronous query operation, in TTID format.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "$ref": "#/components/schemas/LongRunningOperationStatus" }, "statusUrl": { "type": "string", "format": "uri", "description": "The URI to poll for operation status.", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "createdAt": { "type": "string", "format": "date-time", "description": "The time when the operation was accepted, in RFC 3339 UTC format.", "example": "2026-05-25T14:30:00Z" } } }, "QueryJobStatusResponse": { "description": "The status response for an async query operation.\nConforms to LongRunningOperationStatusResponse from Twilio API Standards.\n", "type": "object", "additionalProperties": true, "required": [ "operationId", "status", "createdAt" ], "properties": { "operationId": { "type": "string", "format": "Proc_JobTtid", "description": "The unique identifier for the asynchronous query operation, in TTID format.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "$ref": "#/components/schemas/LongRunningOperationStatus" }, "statusUrl": { "type": "string", "format": "uri", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-05-25T14:30:00Z" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The time when the operation reached a terminal state (CANCELLED, COMPLETED, or FAILED), in RFC 3339 UTC format. Null while the operation is still PENDING or RUNNING.", "example": "2026-05-25T14:32:17Z" }, "error": { "nullable": true, "description": "The error details, present only when status is FAILED.", "allOf": [ { "$ref": "#/components/schemas/OperationError" } ] }, "resultUrl": { "type": "string", "format": "uri", "nullable": true, "description": "The URL to retrieve query results, present only when status is COMPLETED.\nSupports pagination via the pageSize and pageToken query parameters.\n", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r/Results" }, "resultId": { "type": "string", "nullable": true, "description": "The identifier of the results resource, present only when status is COMPLETED.\nEqual to operationId, since results are keyed by the operation ID.\n", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "resultRetentionPeriod": { "type": "string", "format": "duration", "nullable": true, "description": "The duration for how long results are retained, in ISO 8601 format.", "example": "P7D" } } }, "QueryJobListResponse": { "description": "A paginated list of async query operations for the account.", "type": "object", "required": [ "items", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueryJobStatusResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "paths": { "/v3/InsightsDomains/Conversations/Query": { "servers": [ { "url": "https://insights.twilio.com" } ], "post": { "summary": "Execute a synchronous semantic query", "description": "Execute a semantic query against the Conversations domain.\nReturns results inline. For long-running queries, use the QueryJobs endpoint.\n", "tags": [ "TwilioInsights" ], "operationId": "CreateQueryResults", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 20, "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryRequest" } } } }, "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "get": { "summary": "Retrieve paginated query results", "description": "Retrieve subsequent pages of a synchronous query using a page token.", "tags": [ "TwilioInsights" ], "operationId": "FetchQueryResults", "parameters": [ { "name": "pageToken", "in": "query", "description": "Pagination token", "required": true, "schema": { "type": "string", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } ], "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/Metadata": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Retrieve domain metadata", "description": "Returns available cubes, measures, and dimensions for the Conversations domain.", "tags": [ "TwilioInsights" ], "operationId": "FetchMetadata", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsMetadataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } } } }