4xx

400

Used when the request body cannot be parsed, or it contains deceptive routing. If you're looking for validation errors, HTTP 422 is what you're looking for

Example response

{
  "type": "https://developer.vonage.com/api-errors#invalid-json",
  "title": "Malformed JSON",
  "detail": "Malformed JSON payload.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

401

Request is missing API authorization credentials, or those credentials are invalid.

Example response

{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

403

The authenticated user can not make this request. This is not an authentication issue, this is an authorization issue (could be due to low balance, scope of the auth token used, etc).

Important: We use 404 rather than 403 for invalid permissions as we don't want to leak that the resource exists to another user

Example response

{
  "type": "https://developer.vonage.com/api-errors/account/secret-management#maximum-secrets-allowed",
  "title": "Maxmimum number of secrets already met",
  "detail": "This account has reached maximum number of '2' allowed secrets",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

404

The resource could not be found, or the authenticating user does not have access to the resource.

We use 404 rather than 403 for invalid permissions as we don't want to leak that the resource exists to another user

Example response

{
  "type": "https://developer.vonage.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

405

The 405 HTTP code is used when an unsupported HTTP verb is used on a resource.

Example response

{
  "type": "https://developer.vonage.com/api-errors#wrong-verb",
  "title": "Request method not allowed",
  "detail": "Request method 'OPTIONS' not supported",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

406

The 406 HTTP code is used when an unsupported Accept header is supplied

Example response

{
  "type": "https://developer.vonage.com/api-errors#accept-header",
  "title": "Invalid Accept header",
  "detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

409

The request could not be completed due to a conflict with the current state of the resource. The resource exists; however, the action could not be taken. The response MUST contain contain a description of the conflict.

Example response

{
  "type": "https://developer.vonage.com/api-errors#conflict",
  "title": "Conflict",
  "detail": "This resource cannot be updated once the job has started running",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

410

The requested resource is no longer available at the server. This condition is expected to be considered permanent. Used when the URI is formatted correctly, but the subresource is no long available.

Example response

{
  "type": "https://developer.vonage.com/api-errors#gone",
  "title": "Gone",
  "detail": "The resource at this location no longer exists",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

415

The 415 HTTP code is used when an unsupported Content-Type header is supplied

Example response

{
  "type": "https://developer.vonage.com/api-errors#content-type-header",
  "title": "Invalid Content-Type header",
  "detail": "Invalid Content-Type header provided. Must be one of the following: 'application/json'",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

422

Validation error, used when the request does not meet existing validation rules. More details should be available (specific error, and human description) in the response body.

Example response

{
  "type": "https://developer.vonage.com/api-errors/account/secret-management#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "secret",
      "reason": "must contain 1 upper case character"
    }
  ],
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

429

The 429 HTTP code is used when a consumer has exceeded their rate limit

Example response

{
  "type": "https://developer.vonage.com/api-errors#rate-limited",
  "title": "Rate Limited",
  "detail": "You have exceeded your rate limit. You can try again at YYYY-MM-DD HH:mm:ss",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}