Error messages

Examples of error messages or validations returned by the API and what they are

The responses returned by the API follow this standard response format:

{
  "errors": { ... },
  "data": { ... }
}

However, the errors attribute is only returned when an exception occurs in the request.

When an invalid GraphQL query error occurs, the exceptions are similar to the example below (e.g., when a required value like name is missing in the query specification).

{
  "errors": [
    {
      "message": "Variable \"$folder\" got invalid value null at \"folder.name\"; Expected non-nullable type \"String!\" not to be null.",
      "locations": [
        {
          "line": 1,
          "column": 31
        }
      ]
    }
  ]
}

Here's an example of a common error when searching for a nonexistent folder:

{
  "errors": [
    {
      "message": "Folder not found",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "folder"
      ]
    }
  ],
  "data": {
    "folder": null
  }
}

Additionally, there are validation errors (when the message attribute has the value "validation"), such as when creating a folder with an empty string value:

{
  "errors": [
    {
      "message": "validation",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "createFolder"
      ],
      "extensions": {
        "validation": {
          "folder.name": [
            "field_required"
          ]
        },
        "category": "validation"
      }
    }
  ],
  "data": {
    "createFolder": null
  }
}

In the following example, there’s also a validation error, but with variables, which happens when a folder name that is too short is defined:

{
  "errors": [
    {
      "message": "validation",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "createFolder"
      ],
      "extensions": {
        "validation": {
          "folder.name": [
            "must_be_at_least_characters:3"
          ]
        },
        "category": "validation"
      }
    }
  ],
  "data": {
    "createFolder": null
  }
}

Validation Errors

Lastly, here is a JSON with all the possible error or validation messages that may be returned by the API, along with their meanings and any possible variables in curly brackets (e.g., {{variable}}). Note that these do not include GraphQL query errors.

{
  "unauthorized": "You are not authenticated anymore",
  "document_not_found": "Document not found",
  "folder_not_found": "Folder not found",
  "document_signed": "The document was already signed",
  "not_your_turn": "It's not your turn to sign the document",
  "must_be_a_string": "It's only allowed text",
  "must_be_an_array": "It's not a list",
  "not_a_valid_date": "It's not a valid date",
  "must_be_a_valid_email_address": "It is not a valid email",
  "must_be_a_file": "It's not a file",
  "failed_to_upload":  "Error sending a file",
  "could_not_upload_file": "It was not possible to send a file",
  "field_required": "This field is mandatory",
  "unavailable_credits": "You’ve run out of documents. You’ve already created all the documents available in your plan.",
  "unavailable_verifications_credits": "Insufficient additional verification credits.",
  "may_not_be_greater_than": "Cant have more than {{max}} characters",
  "must_be_at_least": "Can't have less than {{min}} characters",
  "format_is_invalid": "The field format is incorrect",
  "invalid_date": "It's not a valid date",
  "without_permission": "You need to be an organization administrator to perform this action..",
  "must_be_a_valid_file": "Only files with the following extensions are allowed {{extensions}}",
  "not_a_member_of_organization": "You need to be a member of the same organization to perform this action."
}

Rate Limit Error

If your user exceeds 60 requests per minute, an error with status code 429 will be returned, with the message:

{
    "message": "Too Many Attempts."
}