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.
invalid_token
The token is invalid, expired, or has not been included in the request.
401 Unauthorized
deprecated_endpoint
404 Not Found
{
"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."
}
]
}
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_blocker
s 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."
}
]
}
internal_server_error
Something went wrong on our end. Please email [email protected] for assistance. Please avoid including any payloads in your email, we will provide a secure link in our response if payload information is necessary.
500 Internal Server Error
Updated 14 days ago