Editar

Compartilhar via


Troubleshooting REST API/OData calls

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.

Troubleshoot web service errors
Web service performance
Analyzing incoming web services request telemetry
Web service telemetry