Error codes — Integration API

Token Endpoint Errors (POST /api/integration/auth/token)

The token endpoint returns errors in the standard OAuth2 format:

{
  "error": "error_code",
  "error_description": "Human-readable description"
}

HTTP Status	OAuth2 code	Description	How to Resolve
`400`	`unsupported_grant_type`	The given `grant_type` is not supported	Use `client_credentials` or `password`
`400`	`invalid_request`	Required parameters missing or malformed	Check that `client_id` and `grant_type` are present
`401`	`invalid_client`	Invalid client ID or client secret	Check the OAuth2 client credentials
`401`	`invalid_grant`	Invalid user credentials (username/password)	Check the user's email and password
`401`	`unauthorized_client`	Client is not allowed to use the requested grant type	Check the API key configuration in IAM

Authenticated endpoints return errors in the standard API format:

{
  "code": "string",
  "message": "string",
  "success": false
}

HTTP Status	Description	Common Cause	How to Resolve
`401 Unauthorized`	Missing or invalid JWT token	`Authorization` header not sent or token expired	Obtain a new token via `POST /api/integration/auth/token`
`403 Forbidden`	Insufficient permissions	User does not have the role required to access the resource	Check the roles assigned to the API key or user in IAM
`403 Forbidden`	Wrong customer	Attempt to access another customer's data	Check the `X-Customer-Id` header or the `customer-id` claim in the JWT
`400 Bad Request`	Domain rule violation	Invalid parameters or business rule not met	Check the error message returned in the `message` field
`400 Bad Request`	Validation error	Required field missing or invalid format	Check the fields sent against the documentation
`500 Internal Server Error`	Internal error	Unexpected server failure	Contact technical support

Domain errors return HTTP 400 with a specific code in the code field:

{
  "code": "DOMAIN_ERROR_CODE",
  "message": "Mensagem descritiva localizada",
  "success": false
}

The message field is localized according to the Accept-Language header (supports pt-BR and en-US).

Always check the success field in the response to determine whether the operation succeeded
Handle expired tokens automatically: when you receive 401, obtain a new token and retry the request
Do not store tokens indefinitely: respect the expires_in returned with the token
Log the error codes to make troubleshooting with the support team easier