API Error Management

The error management system in the public API provides feedback on various types of issues encountered during requests.
Errors can be grouped into business logic errors, validation errors, or authorization-related errors.
These errors enable developers to quickly identify and correct issues based on error codes and messages consistent with Sage Active’s interface.

Business Logic Errors (200)

When an operation fails due to business rules, the API returns a 200 OK status with detailed error messages. These errors mirror those encountered in the Sage Active interface, helping to ensure a consistent user experience.

Example 1: Creating a Customer with createCustomer Mutation
If a customer creation request fails due to duplicate information, such as an existing document ID or VAT number in the organization, the API response includes relevant error messages.

   {
       "errors": [
           {
               "message": "global.businessErrors.documentIdAlreadyExistInOrganization"
           },
           {
               "message": "global.businessErrors.vatNumberAlreadyExistInOrganization"
           }
       ],
       "data": {
           "createCustomer": null
       }
   }

Example 2: Creating an Accounting Entry with CreateAccountingEntryUsingCodes Mutation
When creating an accounting entry, an error might occur if there is an issue with the line amount. The error response reflects this as follows:

   {
       "errors": [
           {
               "message": "accounting.businessErrors.invalidAccountingEntryLineAmount"
           }
       ],
       "data": {
           "createAccountingEntryUsingCodes": null
       }
   }

Header Validation Errors (200)

If required headers are missing in the request, such as the X-OrganizationId, the API returns a 200 OK status with a specific error message, allowing easy identification and correction of the header-related issue.

Example: Missing X-OrganizationId Header
When the X-OrganizationId header is missing, the API response might look like this:

   {
       "errors": [
           {
               "message": "X-OrganizationId header is mandatory"
           }
       ],
       "data": {
           "journalTypes": null
       }
   }

Validation Errors (400)

When a request contains invalid or unrecognized fields, the API returns a 400 Bad Request error, clearly indicating the field causing the issue.

Example: Nonexistent Field in Request Body
If a request includes an undefined field, such as idx in the createAccountingEntryUsingCodes mutation, the API response specifies the exact field and type where the error occurred:

   {
       "errors": [
           {
               "message": "The field `idx` does not exist on the type `AccountingEntryOutputCreateUsingCodesGLDto`.",
               "locations": [
                   {
                       "line": 3,
                       "column": 5
                   }
               ],
               "path": [
                   "createAccountingEntryUsingCodes"
               ],
               "extensions": {
                   "type": "AccountingEntryOutputCreateUsingCodesGLDto",
                   "field": "idx",
                   "responseName": "idx",
                   "specifiedBy": "http://spec.graphql.org/October2021/#sec-Field-Selections-on-Objects-Interfaces-and-Unions-Types"
               }
           }
       ]
   }

Authorization Errors (401)

When access is denied due to authorization issues, the API returns a 401 Unauthorized error with a message that specifies the reason for the denial.

Example 1: Missing X-API-Key in Request Header
If the subscription key is absent in the X-API-Key header, the API returns an error indicating the requirement to include the subscription key:

   {
       "statusCode": 401,
       "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
   }

Example 2: Invalid JWT Token
If the provided JSON Web Token (JWT) is invalid, the API returns an error specifying the token issue. This can occur if the token is expired, malformed, or otherwise not valid:

   {
       "statusCode": 401,
       "message": "Invalid JWT."
   }

Example 3: Expired Token
If the token has expired, the API responds with an error message prompting the user to refresh the token.

   {
        "statusCode": 401,
        "message": "Token expired. Please refresh the token and try again."
   }

Rate Limit (429)

When the number of requests exceeds the allowed rate limit, the API returns a 429 Too Many Requests error, indicating that the client has hit the rate limitation and should wait before making additional requests.

Example: Rate Limit Exceeded
If the request rate surpasses the API’s threshold, the API responds with an error message suggesting a retry after a specified duration.

    { 
        "statusCode": 429, 
        "message": "Rate limit is exceeded. Try again in 49 seconds." 
    }

The value 49 is an example based on when the 429 status code appears; it starts from 60 seconds and counts down.

Server Errors (500)

When a server error occurs, the API returns a 500 Internal Server Error, often indicating issues such as unhandled exceptions or invalid data parsing.

Example: Incorrect Enumeration Value in JournalType.type
If a request includes an incorrect enumeration value for journalType.type, the API may respond with an error indicating that the value cannot be parsed.

{
    "errors": [
        {
            "message": "JournalTypeType cannot parse the given literal of type `EnumValueNode`.",
            "path": [
                "values",
                "type"
            ],
            "extensions": {
                "field": "JournalTypeCreateGLDtoInput.type",
                "fieldType": "JournalTypeType"
            }
        }
    ]
}

Handling Errors for Improved User Experience

For a tailored user experience, refer to the API resources overview / ⚙️User Access Policy Check action, which allows for passing in object names (e.g., createCustomer mutation) to verify if the current user has the necessary permissions.

Additionally, consult the role and solution-based error management information available on the API resources overview / 📝Users & User Management page.
This page explains how different Sage Active solutions (e.g., Starter, Essentials) and associated user roles affect access permissions.