Error Handling

HTTP status error codes

The following table lists the standard HTTP status codes used by the API:

Code	Resolution
400 Bad Request	There might be invalid syntax in the request body.
401 Unauthorized	Ensure you included a valid authorization token in your request.
403 Forbidden	The server understood the request but refuses to authorize it.
404 Not Found	The server cannot find the requested resource.
413 Payload Too Large	The request is too large for the server to process.
429 Too Many Requests	The client has sent too many requests in a given period of time.
500 Internal Server Error	The server encountered an unexpected error while processing the request. Try again later, and contact Vertex Support if the issue persists.

400 Response example

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "https://developer.vertexinc.com/problems/invalid-request",
  "title": "Bad request",
  "status": 400,
  "detail": "The request body is invalid. 'uniqueIdentifierType' is missing.",
  "instance": "/smartcategorization/categorize"
}

401 Response example

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "type": "https://developer.vertexinc.com/problems/invalid-token",
  "title": "Invalid token",
  "status": 401,
  "detail": "The bearer token is missing, expired, or invalid for this resource.",
  "instance": "/smartcategorization/categorize"
}

403 Response example

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "type": "https://developer.vertexinc.com/problems/insufficient-permissions",
  "title": "Insufficient permissions",
  "status": 403,
  "detail": "The caller does not have permission to persist categorization results for the specified client.",
  "instance": "/smartcategorization/categorize/persist"
}

413 Response example

HTTP/1.1 413 Payload Too Large
Content-Type: application/json

{
  "type": "https://developer.vertexinc.com/problems/payload-too-large",
  "title": "Payload too large",
  "status": 413,
  "detail": "The request body exceeds the maximum supported size of 26 MB or 1,000 products.",
  "instance": "/smartcategorization/categorize"
}

429 Response example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "type": "https://developer.vertexinc.com/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded the allowed request rate. Please retry after 60 seconds."
}

500 Response example

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "type": "https://developer.vertexinc.com/problems/internal-server-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred while processing the request."
}