Troubleshooting REST API/OData calls

Article
02/06/2024

When troubleshooting failed REST API/OData calls, you have many tools/techniques available to you:

Telemetry
HTTP status codes
OData error codes

AL debugger

Troubleshoot failed REST API/OData calls with telemetry

Business Central telemetry on REST API/OData web service calls have two important dimensions to troubleshoot failed web service calls: httpStatusCode and failureReason. The httpStatusCode dimension stores the HTTP return code provided by the Business Central server. The failureReason dimension stores the exception types described earlier. These dimensions aren't available in telemetry for SOAP calls.

Tip

The custom dimension category holds information about the type of endpoint (REST API, OData, or SOAP) being called.

For more information about web services telemetry (including KQL code samples), see Analyzing Incoming Web Services Request Telemetry.

Troubleshoot failed REST API/OData calls with HTTP status codes

When you call a web service endpoint, either a Business Central REST API or an OData-enabled page/query/codeunit, you get an HTTP status code as part of the response. All HTTP status codes that start with 4 (sometimes also written 4xx) are classified as client errors, and it's your responsibility to react on these errors and fix them in your code.

Note

For on-premises environments where SOAP, OData, or APIs have been turned off, any call to such an endpoint will also return a HTTP status code 405 (so check your server configurations if you see those).

For more information, see Troubleshooting web service errors with HTTP status codes.

Error messages and error codes for REST API/OData failures

If a call to a REST API or OData endpoint fails, the Business Central server returns an error message and an error code in the response. Error codes can be divided into the following categories and described as follows:

If you see an error code like this...	It is because...	Do the following to resolve the issue...
BadRequest_*	Is typically an error in the forming of the request or an error accessing the service.	Resolve the bug in the forming of the request. Use the information provided by the AL runtime exception to learn more about the nature of the error.
Authentication_*	An error authenticating to the service.	Attempt to use different credentials.
Authorization_*	The authenticated identity doesn't have the correct permissions.	Attempt operation using different credentials.
Internal_*	Typically the error is an internal error in the application on the server or data integrity issue. For example, the Business Central server can't communicate with the SQL Server.	Attempt the operation again. Resolve data issues. Use the information provided by the AL runtime exception to learn more about the nature of the error.
Application_*	Typically an application logic error.	Request is made again with updated data. Use the information provided by the AL runtime exception to learn more about the nature of the error.

The following table explains how the OData error codes/messages translate to exceptions thrown by the AL runtime. The same OData error code appears multiple times in the table, each entry with a different AL runtime exception type. The OData error code tells you the type of error as seen from the OData layer, whereas the exception type tells you more about the root cause of the error as seen from the AL runtime.

AL runtime exception	OData error code	OData error message
ODataArgumentException	BadRequest_InvalidRequestUrl	An incompatible property definition already exists for `'Allowed_Companies_0.Name'`
ODataNotFoundException	BadRequest_NotFound	Bad Request - Error in query syntax
ODataNotFoundException	BadRequest_NotFound	Expression expected at position 153 in '(AAMkAGY2ZTQwODIwLTNkOWYtN DY3NC04N2JkLTE3MDEyNzlkM2VkOQBGAAAAAAD FMnbflwH_RqlNoMYdjhvBBwCepO6AHq7GRJ13ldPngx5BAAAAAAEcAA CepO6AHq7GRJ13ldPngx5BAAAGZyTmAAA=)'
ODataNotFoundException	BadRequest_NotFound	'\|' or ',' expected at position 3 in (GUID)
ODataResourceNotFoundException	BadRequest_ResourceNotFound	Resource not found for the segment `'OfficeAppResourceRegistrations'` multiple segment errors (Company, v2.0, nativeInvoicingSalesInvoices,metadata, nativeInvoicingItems, companies,company etc.)
ODataInvalidOperationException	BadRequest_InvalidOperation	Control `'Last Date Modified'` is read-only
ODataBadRequestException	BadRequest	Invalid Request Body
ODataBadRequestException	BadRequest	Unable to convert value to Date
ODataBadRequestInvalidTokenException	BadRequest_InvalidToken	Could not validate the client concurrency token required by the service. Please provide a valid token in the client request.
ODataBadRequestNullFieldException	BadRequest_RequiredParamNotProvided	Field `'taxable'` must not be blank or empty.
ODataConflictException	Request_EntityChanged	Another user has already changed the record.
ODataMethodNotAllowedException	BadRequest_MethodNotAllowed	`'POST'` requests for `'companies'` of EdmType `'Entity'` are not allowed within Microsoft Dynamics NAV OData web services.
ODataNotImplementedException	BadRequest_MethodNotImplemented	Entity does not support bound actions or an orderby query option did not match the default OrderBy fields of an underlying Query object.
NavCSideDataException	Internal_DataNotFoundFilter	There is no Cust. Ledger Entry within the filter.
NavCSideRecordNotFoundException	Internal_RecordNotFound	The Acc. Sched. KPI Web srv. Setup does not exist. Identification fields and values: Primary Key=''
NavCSideValidateTableRelationException	Internal_InvalidTableRelation	The field Account No. of table Gen. Journal Line contains a value (ABL001) that cannot be found in the related table (Vendor).
NavCSideException	Internal_ServerError	Cannot establish a connection to the SQL Server/Database.
NavCSideDuplicateKeyException	Internal_EntityWithSameKeyExists	The Attachment Entity Buffer already exists. Identification fields and values: Document Id= '{DAC3AB2F-5FEA-4AD2-A663-EF832F270A7B}',Id=' {00000000-0000-0000-0000-000000000000}'
NavCompanyNotFoundException	Internal_CompanyNotFound	Cannot process the request because the default company cannot be found. You can specify a default company in the service configuration file, or specify one for each tenant, or you can add a query string in the form of "company=[name]". You can see the available companies by accessing the default OData web service, Company. For more information, see "OData Web Services" in Help
NavTenantNotAccessibleException	Internal_TenantUnavailable	The tenant 'msca1a7355t05263373' is not accessible
NavNCLDialogException	Application_DialogException	You cannot delete Item 1000 because there is at least one outstanding Sales Quote that includes this item.
NavNCLDialogException	Application_DialogException	A customerNumber or a customerID must be provided.
NavNCLDialogException	Application_DialogException	You may not enter numbers manually. If you want to enter numbers manually, please activate Manual Nos. in No. Series FA.
NavNCLDialogException	Application_DialogException	You are not allowed to apply and post an entry to an entry with an earlier posting date.
NavNCLDialogException	Application_DialogException	The "amount" should be a negative number.
NavNCLEvaluateException	Application_EvaluateException	The value "Depreciation" cannot be evaluated into type Option.
NavNCLStringLengthExceededException	Application_StringExceededLength	The length of the string is 57, but it must be less than or equal to 50 characters. Value: JACKSBORO PUMP & SPECIALTY BRIDGEPORT PUMP & SUPPLY, INC.
NavNCLInvalidGuidFormatException	Application_InvalidGUID	Invalid format of GUID string. The correct format of the GUID string is: CDEF7890-ABCD-0123-1234-567890ABCDEF where 0-9, A-F symbolizes hexadecimal digits.
NavNCLCallbackNotAllowedException	Application_CallbackNotAllowed	Microsoft Sync 365 for fin Data services attempted to issue a client callback to show a confirmation dialog box. We found an item with the description
NavFilterException	Application_FilterErrorException	The filter `"='SELLACRE24_W%2FOORINGS'"` is not valid for the No. field on the Item table. The length of the string is 22, but it must be less than or equal to 20 characters. Value: `SELLACRE24_W%2FOORINGS`
NavTestFieldException	Application_FieldValidationException	Balance must be equal to '0' in G/L Account: No.=10100. Current value is '1,638.4'. Customer Posting Group must have a value in Customer: No.=C00690. It cannot be zero or empty.
NavTestFieldException	Application_FieldValidationException	Customer Posting Group must have a value in Customer: No.=C00690. It cannot be zero or empty.
NavInvalidCredentialException	Authentication_InvalidCredentials	The server has rejected the client credentials
Any	Unknown	Any

Debugging code called from a web service endpoint

This article is covered in the general troubleshooting guide for web services. For more information, see Debugging code called from a web service endpoint.

Explore REST APIs with an API explorer

There are tools available for exploring and testing REST APIs. When troubleshooting API issues, consider using a tool, such as Insomnia, Bruno, or Insomnium to interact with the API endpoint to "debug" the API as seen from the web service client point of view. This technique is particularly useful if you are not allowed to debug the AL code for the API endpoint.

Which IP addresses or ranges does my environment use?

This article is covered in the general troubleshooting guide for web services. For more information, see Which IP addresses or ranges does my environment use?.

It works in my sandbox but not in production

This article is covered in the general troubleshooting guide for web services. For more information, see It works in my sandbox but not in production.