Error Categories

The following error samples provide a comprehensive list of all error categories we currently support. You may use the category to programmatically handle errors in your integration.

deprecated_endpoint

404 Not Found

{
  "errors": [
    {
      "error_key": "request",
      "category": "deprecated_endpoint",
      "message": "The requested endpoint is no longer supported in the requested API version."
    }
  ]
}

duplicate_operation

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "base",
      "category": "duplicate_operation",
      "message": "Cannot have multiple of the same state field per company"
    }
  ]
}

internal_error

If an internal error occurs, our engineers are notified to investigate the problem.

500 Internal Server Error

{
  "errors": [
    {
      "error_key": "request",
      "category": "internal_error",
      "message": "An unexpected error has occurred."
    }
  ]
}

invalid_api_version

To learn more about API Versions review our API Versioning guide.

406 Not Acceptable

{
  "errors": [
    {
      "error_key": "request",
      "category": "invalid_api_version",
      "message": "Invalid API Version `2023`. Expected format: YYYY-MM-DD"
    }
  ]
}

invalid_application_setup

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "request",
      "category": "invalid_application_setup",
      "message": "You must create an application to continue."
    }
  ]
}

invalid_attribute_value

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "fast_payment_limit",
      "category": "invalid_attribute_value",
      "message": "Fast payment limit should be a number"
    }
  ]
}

invalid_operation

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "base",
      "category": "invalid_operation",
      "message": "Bank account cannot be verified. Please check the test deposit amounts."
    }
  ]
}

invalid_parameter

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "benefit_id",
      "category": "invalid_parameter",
      "message": "Parameter `benefit_id` is deprecated in this API version. Please use `benefit_type`"
    }
  ]
}

invalid_resource_version

409 Conflict

{
  "errors": [
    {
      "error_key": "base",
      "category": "invalid_resource_version",
      "message": "You are attempting to update a resource using an out-of-date version."
    }
  ]
}

missing_oauth_scopes

403 Forbidden

{
  "errors": [
    {
      "error_key": "request",
      "category": "missing_oauth_scopes",
      "message": "You do not have the necessary OAuth scopes for this request. Please reach out to [email protected] for assistance."
    }
  ]
}

missing_parameter

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "base",
      "category": "missing_parameter",
      "message": "benefit_type is required."
    }
  ]
}

missing_permissions

403 Forbidden

{
  "errors": [
    {
      "error_key": "request",
      "category": "missing_permissions",
      "message": "This endpoint is part of Gusto Embedded. Please contact [email protected] if you’d like to have more information and use it for production. Note, this may require you to enter a different agreement with Gusto."
    }
  ]
}

nested_errors

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "fields",
      "category": "nested_errors",
      "errors": [
        {
          "error_key": "signature",
          "category": "invalid_attribute_value",
          "message": "Field is required."
        }
      ]
    }
  ]
}

not_found

404 Not Found

{
  "errors": [
    {
      "error_key": "request",
      "category": "not_found",
      "message": "This endpoint does not exist on this version of the Gusto API."
    }
  ]
}

payroll_blocker

To see a list of all possible payroll_blockers review the Payroll Blockers guide.

422 Unprocessable Entity

{
  "errors": [
    {
      "error_key": "base",
      "category": "payroll_blocker",
      "message": "Company or employee address could not be verified. Please ensure all addresses are valid.",
      "metadata": {
        "key": "geocode_error"
      }
    }
  ]
}

rate_limit_exceeded

To learn more about our rate limits review the Rate Limits guide.

429 Too Many Requests

{
  "errors": [
    {
      "error_key": "base",
      "category": "rate_limit_exceeded",
      "message": "Rate limit exceeded. Please wait a bit before trying again."
    }
  ]
}