{
  "openapi": "3.1.0",
  "info": {
    "title": "Sonaline Messaging API",
    "version": "1",
    "description": "Send and receive texts and pictures from a workspace's numbers, list the message history with its delivery quality, and keep files to send. Bandwidth's paths, fields and error body. The guide: https://sonaline.com/developers/messaging",
    "contact": {
      "email": "hello@sonaline.com"
    }
  },
  "servers": [
    {
      "url": "https://api.sonaline.com/api/v2/users/{accountId}",
      "variables": {
        "accountId": {
          "default": "0000000",
          "description": "Your account number, shown beside your credentials."
        }
      }
    }
  ],
  "paths": {
    "/api/v1/oauth2/token": {
      "post": {
        "operationId": "post_oauth2_token",
        "summary": "Get a bearer token, good for an hour, for a client id and secret (OAuth 2 client credentials).",
        "x-sonaline-token-door": true,
        "x-sonaline-effect": "changes",
        "servers": [
          {
            "url": "https://api.sonaline.com"
          }
        ],
        "security": [
          {
            "basic": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Instead of Basic: the client id."
                  },
                  "client_secret": {
                    "type": "string",
                    "writeOnly": true,
                    "format": "password",
                    "description": "Instead of Basic: the secret. Never in a query string."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A token.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "access_token",
                    "token_type",
                    "expires_in"
                  ],
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "access_token_id": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    },
                    "expires_in": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/OAuthError"
          },
          "401": {
            "$ref": "#/components/responses/OAuthError"
          },
          "405": {
            "$ref": "#/components/responses/OAuthError"
          },
          "413": {
            "$ref": "#/components/responses/OAuthError"
          },
          "429": {
            "$ref": "#/components/responses/OAuthError"
          },
          "503": {
            "$ref": "#/components/responses/OAuthError"
          }
        }
      }
    },
    "/media": {
      "get": {
        "operationId": "get_media",
        "summary": "List the account's uploads, up to 1000 at a time; a Continuation-Token header gives the next page.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/media/{mediaId}": {
      "get": {
        "operationId": "get_media_by_media",
        "summary": "Download an upload or a message's own part, with its Content-Type.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "An upload's name (letters, digits, '.', '_' and '-', at most 200, starting with a letter or a digit); to download, also a message's own part, <messageId>/<n>/<name>.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "head": {
        "operationId": "head_media_by_media",
        "summary": "The headers of a download, without its bytes.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "An upload's name (letters, digits, '.', '_' and '-', at most 200, starting with a letter or a digit); to download, also a message's own part, <messageId>/<n>/<name>.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "put": {
        "operationId": "put_media_by_media",
        "summary": "Upload a file to send, under a name of yours; the same name replaces it. Kept 30 days.",
        "description": "At most 3,750,000 bytes; the account keeps at most 1,000 uploads and 1 GB.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "sends and uploads",
        "x-sonaline-effect": "changes",
        "x-sonaline-inputs": "written",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "An upload's name (letters, digits, '.', '_' and '-', at most 200, starting with a letter or a digit); to download, also a message's own part, <messageId>/<n>/<name>.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "*/*": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "operationId": "delete_media_by_media",
        "summary": "Delete an upload. A message's own parts cannot be deleted.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "sends and uploads",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "An upload's name (letters, digits, '.', '_' and '-', at most 200, starting with a letter or a digit); to download, also a message's own part, <messageId>/<n>/<name>.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/messages": {
      "get": {
        "operationId": "get_messages",
        "summary": "List and search the account's messages, newest first, a page at a time; the list holds no message text.",
        "description": "Include at least one query parameter.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "x-sonaline-inputs": "written",
        "parameters": [
          {
            "name": "messageId",
            "in": "query",
            "required": false,
            "schema": {
              "description": "One message.",
              "type": "string"
            }
          },
          {
            "name": "sourceTn",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A full E.164 number, up to 10 of them comma-separated, or one partial number of 5 characters or more, matched from the start.",
              "type": "string"
            }
          },
          {
            "name": "destinationTn",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A full E.164 number, up to 10 of them comma-separated, or one partial number of 5 characters or more, matched from the start.",
              "type": "string"
            }
          },
          {
            "name": "messageStatus",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "RECEIVED",
                "QUEUED",
                "SENDING",
                "SENT",
                "FAILED",
                "DELIVERED",
                "ACCEPTED",
                "UNDELIVERED"
              ]
            }
          },
          {
            "name": "messageDirection",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "INBOUND",
                "OUTBOUND"
              ]
            }
          },
          {
            "name": "messageType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sms",
                "mms"
              ]
            }
          },
          {
            "name": "errorCode",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A failure code, for example 4750.",
              "type": "string"
            }
          },
          {
            "name": "fromDateTime",
            "in": "query",
            "required": false,
            "schema": {
              "description": "ISO 8601, compared with receiveTime.",
              "type": "string"
            }
          },
          {
            "name": "toDateTime",
            "in": "query",
            "required": false,
            "schema": {
              "description": "ISO 8601, compared with receiveTime.",
              "type": "string"
            }
          },
          {
            "name": "campaignId",
            "in": "query",
            "required": false,
            "schema": {
              "description": "Your 10DLC campaign id.",
              "type": "string"
            }
          },
          {
            "name": "fromSegmentCount",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The least segment count.",
              "type": "string"
            }
          },
          {
            "name": "toSegmentCount",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The most segment count.",
              "type": "string"
            }
          },
          {
            "name": "carrierName",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The destination or source carrier.",
              "type": "string"
            }
          },
          {
            "name": "fromNetworkLatency",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The least latency through the network, in seconds.",
              "type": "string"
            }
          },
          {
            "name": "fromCarrierLatency",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The least latency at the destination carrier, in seconds (OUTBOUND only).",
              "type": "string"
            }
          },
          {
            "name": "networkQueued",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "carrierQueued",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "description": "LOCAL_A2P, P2P, SHORT_CODE_REACH, TOLL_FREE, HOSTED_SHORT_CODE, ALPHA_NUMERIC, RBM_MEDIA, RBM_RICH or RBM_CONVERSATIONAL.",
              "type": "string"
            }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The location id.",
              "type": "string"
            }
          },
          {
            "name": "callingNumberCountryA3",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A three-letter country code.",
              "type": "string"
            }
          },
          {
            "name": "calledNumberCountryA3",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A three-letter country code.",
              "type": "string"
            }
          },
          {
            "name": "fromMessageSize",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The least message size.",
              "type": "string"
            }
          },
          {
            "name": "toMessageSize",
            "in": "query",
            "required": false,
            "schema": {
              "description": "The most message size.",
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "description": "A field of a message, then :asc or :desc. Default receiveTime:desc.",
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "description": "Page size. Default 100.",
              "type": "string"
            }
          },
          {
            "name": "pageToken",
            "in": "query",
            "required": false,
            "schema": {
              "description": "From pageInfo.nextPageToken or prevPageToken; pass the same filters again.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "operationId": "post_messages",
        "summary": "Send a text or a picture message from one of the account's numbers; several numbers in to make a group.",
        "description": "202 means accepted for sending, not delivered: delivery is reported by callback. Send an Idempotency-Key so a retry never sends twice.",
        "security": [
          {
            "bearer": [
              "messaging"
            ]
          },
          {
            "basic": [
              "messaging"
            ]
          }
        ],
        "x-sonaline-scope": "messaging",
        "x-sonaline-rate": "sends and uploads",
        "x-sonaline-effect": "sends",
        "x-sonaline-confirm": true,
        "x-sonaline-unknown-outcome-keeps-key": true,
        "x-sonaline-inputs": "written",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "applicationId": {
                    "description": "One of your applications: this message's status callbacks go to its callback URL.",
                    "type": "string"
                  },
                  "to": {
                    "description": "E.164 numbers. More than one makes one group MMS. No repeats.",
                    "type": "array",
                    "minItems": 1
                  },
                  "from": {
                    "description": "One of the account's numbers, in E.164.",
                    "type": "string"
                  },
                  "text": {
                    "description": "The words, at most 2048 characters. Send text, media or both.",
                    "type": "string",
                    "maxLength": 2048
                  },
                  "media": {
                    "description": "URLs of files to send, each at most 4096 characters: public https, or an upload of yours.",
                    "type": "array"
                  },
                  "tag": {
                    "description": "Your own string, at most 1024 characters, given back on this message's callbacks.",
                    "type": "string",
                    "maxLength": 1024
                  },
                  "priority": {
                    "type": "string",
                    "enum": [
                      "default",
                      "high"
                    ]
                  },
                  "expiration": {
                    "description": "An RFC 3339 date-time in the future.",
                    "type": "string"
                  }
                },
                "required": [
                  "applicationId",
                  "to",
                  "from"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "oauth2",
        "description": "A token from the token door, good for an hour, sent as Authorization: Bearer.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.sonaline.com/api/v1/oauth2/token",
            "scopes": {
              "messaging": "Use the Messaging API."
            }
          }
        }
      },
      "basic": {
        "type": "http",
        "scheme": "basic",
        "description": "The client id and secret on each request."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "1 to 100 visible characters. The same request with the same key is answered once; its first answer is given again for 24 hours.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Made by Sonaline for this request. Quote it to support.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitLimit": {
        "description": "The most requests of this kind in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "What is left in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "Invalid": {
        "description": "A field is missing or wrong. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "No credential, or a wrong or expired one. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Not this credential's account, or a scope or switch refuses it. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such path or thing on this account.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "The web framework's body, as Bandwidth's.",
              "properties": {
                "timestamp": {
                  "type": "string"
                },
                "status": {
                  "type": "integer"
                },
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "A method the path does not take; Allow names the ones it does. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Allow": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "Conflict": {
        "description": "The route's own conflict (a name taken, a limit reached), or a request with this Idempotency-Key still running or with no answer. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "The body is over its size. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnsupportedType": {
        "description": "The body is not of a type the route takes. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Failed": {
        "description": "Something failed on Sonaline's side, or a carrier refused. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadGateway": {
        "description": "The service behind the API failed or did not answer (`box_unreachable`). Try again in a moment. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "The service behind the API did not answer in time: what was asked may have been done. Check before trying again. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "Not available just now: try again in a moment. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      },
      "OAuthError": {
        "description": "OAuth 2's error body (RFC 6749): {error, error_description}. A 429 carries Retry-After, a 405 Allow.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                },
                "error_description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "IdempotencyMismatch": {
        "description": "The Idempotency-Key was used on another request. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests (`rate_limited`): wait Retry-After seconds. The body is Bandwidth's {type, description}; the types are in the guide's Errors table.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "type",
          "description"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Stable: what to act on (the guide's Errors table)."
          },
          "description": {
            "type": "string",
            "description": "Plain words; may change."
          },
          "fieldErrors": {
            "type": "array",
            "description": "On a refused send: each field that is wrong.",
            "items": {
              "type": "object",
              "properties": {
                "fieldName": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
