Error Response Body

The error response is returned whenever a request to the bizAPIs API cannot be completed successfully.
It provides information about what went wrong, where the error originated, and a human-readable explanation. This structure is designed to be machine-readable for automated handling and human-readable for troubleshooting.

🔔 Migration Guide: New Enhanced Error Response Structure

What's Changing

We're introducing a new structured error response format across all bizAPIs endpoints to improve debugging, monitoring, and support experiences.

Before (Old Format)

{
  "message": "Document not found"
}

After (New Format)

{
    "errorResponse": {
        "requestId": "e18b757e-c99c-4705-8bdc-d35ee6dbbfdf",
        "errorCode": 2,
        "errorName": "AUTHENTICATION_INVALID_CREDENTIALS",
        "fullStatusCode": "0002.0025.0003",
        "timestamp": "2026-01-14T14:10:07.291Z",
        "message": "Invalid credentials provided. Please check your username and password."
    }
}

Why This Matters

✅ Faster Support - Share the requestId with our team to instantly locate your request in our logs
✅ Better Debugging - The fullStatusCode tells you exactly what failed, in which service, and from where
✅ Programmatic Handling - Use errorCode or errorName for consistent error handling across your application
✅ Audit Trail - timestamp helps you correlate errors with your own logs

Breaking Changes

⚠️ Action Required:

Response Structure Changed - Error responses now return a structured JSON object with new fields
Error Message Difference - Some messages may have changed in order to standardized across all services

When contacting support, always include:

The requestId from the error response
The fullStatusCode if available
Timestamp of when the error occurred
What you were trying to accomplish

Fields

Field	Type	Example	Description
`requestId`	`String`	`"9e12f4b8-7d4f-4a9f-b832-5c614e86d5aa"`	A unique identifier for this specific API request. Useful for tracing and debugging in logs.
`errorCode`	`short`	`4099`	A numeric code that uniquely identifies the type of error. Can be mapped to predefined error codes documented in the Error Codes table below.
`errorName`	`String`	`"DOCUMENT_NOT_FOUND"`	A machine-readable name for the error. Matches the constant name from the Error Codes table.
`fullStatusCode`	`String`	`"4099.0008.0002"`	A composite status code made up of three parts: `[errorCode].[serviceCode].[originCode]`. This allows precise identification of what error occurred, in which service, and from which origin.
`timestamp`	`Instant` (ISO 8601 format)	`"2025-08-13T16:37:53.037939200Z"`	The exact date and time (in UTC) when the error occurred.
`message`	`String`	`"Document not found"`	A human-readable explanation of the error intended for display in logs, UI messages, or debugging tools.

Understanding`fullStatusCode`

The fullStatusCode provides a structured way to trace errors:

[errorCode].[serviceCode].[originCode]

errorCode → Maps to the main error type (see Error Codes Table below).
serviceCode → Identifies which internal bizAPIs service was involved (see Service Codes Table below).
originCode → Identifies the origin of the request or error trigger (see Origin Codes Table below).

Example:

4099.0008.0002

4099 → DOCUMENT_NOT_FOUND
0008 → cpp-service
0002 → Originated from PORTAL

Error Codes

1. Authentication & Login Failures (0–2048)

Key	code	message
AUTHENTICATION_FAILED	0	Authentication failed. Please verify your credentials and try again.
AUTHENTICATION_TIMEOUT	1	Authentication timed out. The service is taking longer than expected to respond.
AUTHENTICATION_INVALID_CREDENTIALS	2	Invalid credentials provided. Please check your username and password.
AUTHENTICATION_PAGE_UNREACHABLE	3	Unable to reach authentication page.
AUTHENTICATION_CAPTCHA_FAILED	4	Authentication failed due to CAPTCHA verification. Please try again.
AUTHENTICATION_PASSWORD_RECOVERY_REQUIRED	5	Password recovery is required. Please reset your password to continue.
AUTHENTICATION_SESSION_EXPIRED	6	Session expired or not found. Please authenticate again.
AUTHENTICATION_OTP_ERROR	7	Failed to submit OTP. An error occurred during the process.
AUTHENTICATION_OTP_EXCEPTION	8	Failed to submit OTP. An exception occurred in the process.
AUTHENTICATION_OTP_ATTEMPTS_EXCEEDED	9	Number of OTP attempts is about to be exceeded. Please authenticate manually to avoid account lockout.

2. Data Extraction & Processing Failures (2049–4096)

Key	code	message
EXTRACTION_FAILED	2049	Failed to extract the requested data. Please try again later.
EXTRACTION_PENDING_DECISION	2051	Data extraction is pending decision. Please try again later.
PDF_GENERATION_FAILED	2052	Failed to generate PDF document. Please try again.
DOCUMENT_SEARCH_FAILED	2053	Error occurred while searching for the document. Please try again.
REQUEST_PROCESSING_FAILED	2054	Unable to process your request. Please try again later.
DOCUMENT_READ_FAILED	2055	Failed to read the document. The file may be corrupted or inaccessible.
SERVICE_DOWNLOAD_DISABLED	2058	Download functionality is currently disabled for this service.
SERVICE_ERROR	2059	A service error occurred. Please try again later.

3. Resource Not Found or Unavailable (4097–6144)

Key	code	message
RESOURCE_UNAVAILABLE	4097	The requested resource is currently unavailable. Please try again later.
RESOURCE_NOT_FOUND	4099	The requested resource was not found.
DATE_NOT_AVAILABLE	4103	The selected date is not available. Please choose a different date.
NIF_WITHOUT_ACTIVITY	4104	No activity is registered for this tax identification number.
NIF_NONEXISTENT	4105	The provided tax identification number does not exist.
TAX_NUMBER_OUTDATED	4106	The tax number is outdated. Please provide the current tax identification number.
PORTAL_ACCESS_FAILED	4108	Failed to access the portal. Please try again later.

4. Timeout & Page Load Issues (6145–8192)

Key	code	message
TIMEOUT_OCCURRED	6145	Operation timed out. The service is taking longer than expected to respond.
TIMEOUT_FILE_READ	6146	File read operation timed out. Please try again.
TIMEOUT_DATA_EXTRACTION	6148	Data extraction timed out. Please try again later.
TIMEOUT_SEARCH	6149	Search operation timed out. Please try again.

5. Input Validation & Formatting Errors (8193–10240)

Key	code	message
INVALID_NIF	8193	The provided tax identification number is not valid.
FIELD_PAGE_CANNOT_BE_NEGATIVE	8194	Page number cannot be negative. Please provide a valid page number.
FIELD_PAGE_EXCEEDS_LIMIT	8195	Page number exceeds the maximum limit.
NUMBER_VALUES_REQUESTS_EXCEEDS_NUMBER_OF_RESULTS	8196	The number of requested values exceeds the available results.
MISSING_INPUTS	8197	Required input fields are missing. Please provide all necessary information.
SERVICE_NOT_IDENTIFIED	8198	No service identified. Please specify which service you want to use.
LICENSE_SERVICE_LIMIT_EXCEEDED	8199	Your license does not allow multiple services simultaneously. Please use one service at a time.
SERVICE_NOT_ALLOWED_FOR_LICENSE	8200	The requested service is not included in your license.
PORTAL_SERVICE_ERROR	8201	An error was reported by the portal service. Please contact support if this persists.
PARSING_ERROR	8202	Failed to parse the provided data. Please check the format and try again.
DATE_NOT_ALLOWED	8203	The provided date is not allowed. Date must be within the last 5 years.
MONTH_NOT_AVAILABLE	8204	The requested month is not available.
CONFIGURATION_ERROR	8205	A configuration error occurred. Please contact support.

Service Codes

Key	Value
crc-service	1
ies-service	2
nif-name-service	3
ce-service	4
debt-service	5
estado-empresa-service	6
rcbev2-service	7
cpp-service	8
at-docs-service	9
at-pi-service	10
at-irc-service	11
at-iva-dp-service	12
at-alerts-service	13
at-iva-sa-service	14
at-divida-service	15
at-iva-enquadramento-service	16
at-interacoes-service	17
at-aggregator-service	18
irs-by-code-service	19
irs-by-user-password-service	20
responsabilidade-credito-service	21
seguro-by-matricula-service	22
vehicle-by-nif-service	23
ss-no-debt-service	24
ss-docToPay-service	25
ss-sa-service	26
responsabilidade-credito-details-service	27
irs-by-user-password-details-service	28

Origin Codes

Key	Value
BIZAPIS	1
PORTAL	2
USER	3