Business Central API Error Handling: 400, 401, 403, 404, 409 & 429 Explained

Dynexal • Beginner to Intermediate • 16 min read

Business Central integrations rarely fail because of one mysterious problem. Most API failures can be understood quickly when you identify the HTTP status code, inspect the response body, verify authentication and permissions, and then apply the right retry or correction strategy.

Why API error handling matters

A successful HTTP connection does not automatically mean a successful business operation. An external system can return a valid HTTP response with a client or server error status, while Business Central can also report AL runtime or application errors.

A reliable integration should therefore separate three questions: did the HTTP request get sent, did the server return a successful status, and did the response contain the expected business data?

Microsoft Learn: Troubleshooting REST API/OData calls

Business Central API HTTP status codes at a glance

• 200 OK: the operation completed successfully and normally returned a response body.
• 201 Created: a resource was created successfully when supported by the endpoint.
• 204 No Content: the operation succeeded without a response body.
• 400 Bad Request: the request is malformed, invalid, or contains unacceptable data.
• 401 Unauthorized: authentication is missing, invalid, expired, or otherwise unacceptable.
• 403 Forbidden: the identity is authenticated but does not have the required permission.
• 404 Not Found: the endpoint or requested resource cannot be found.
• 405 Method Not Allowed: the HTTP method is not supported for that resource.
• 409 Conflict: the operation conflicts with the current resource or business state; inspect the endpoint response because the exact conflict behavior depends on the API.
• 429 Too Many Requests: the client has exceeded API limits and should back off before retrying.
• 500/503: a server-side or temporary service problem; investigate the response and retry only when appropriate.
• 504 Gateway Timeout: the request took too long and should usually be redesigned or split rather than blindly retried.

Microsoft specifically documents 4xx responses as client errors and recommends using HTTP status codes, telemetry, error codes and the AL debugger when troubleshooting REST API/OData calls.

400 Bad Request

A 400 response usually means the request itself needs correction. Common causes include an invalid URL, malformed JSON, invalid property names, wrong data types, unsupported query syntax or business validation failures.

Example troubleshooting checklist

1. Check the exact endpoint URL.
2. Validate the JSON structure and property names.
3. Check required fields and data types.
4. Review $filter, $select and other query parameters.
5. Read the response body instead of looking only at the status number.

401 Unauthorized

HTTP 401 usually points to authentication. Check the access token, token expiration, audience or scope, tenant, client credentials and the Authorization header.

Headers := Request.GetHeaders();
Headers.Add('Authorization', 'Bearer ' + AccessToken);

if not Client.Send(Request, Response) then
    Error('HTTP request could not be sent.');

if Response.HttpStatusCode() = 401 then
    Error('Authentication failed. Check the access token, tenant and scope.');

Do not hard-code production secrets in AL source code. Use the authentication and secret-management approach appropriate to the integration.

403 Forbidden

A 403 response normally means the server understood the identity but that identity is not allowed to perform the requested operation. In Business Central, review users, permission sets, table permissions, API page permissions and the permissions of the application identity being used.

This is an important distinction: obtaining a valid token does not automatically grant access to every Business Central company, API or operation.

404 Not Found

Check both the route and the resource identifier. A 404 can come from a wrong environment, company ID, API version, publisher/group/entity name, record ID or endpoint path.

ApiUrl :=
    BaseUrl + '/v2.0/' + Tenant +
    '/api/dynexal/integration/v1.0/companies(' +
    CompanyId + ')/customers';

For custom APIs, verify APIPublisher, APIGroup, APIVersion, entity set naming and the company segment. A single URL character can produce a 404.

405 Method Not Allowed

When you receive 405, the endpoint exists but the operation is not allowed for that resource or HTTP method. For example, an endpoint may support GET but not DELETE, or a read-only API query may not support write operations.

Compare the method with the API contract before changing authentication or permissions.

409 Conflict

A conflict means the requested operation cannot be completed in the current state. In integration scenarios this can happen when another process has changed the resource, when a duplicate or conflicting business record exists, or when the endpoint's concurrency rules reject the request.

Do not blindly retry every 409. Read the response, determine whether the conflict is temporary or requires a business decision, and then refresh or reconcile the data when appropriate.

429 Too Many Requests

HTTP 429 means throttling has occurred because API limits have been exceeded. The correct response is controlled retry logic with a cool-off period rather than immediately sending the same request repeatedly.

if Response.HttpStatusCode() = 429 then begin
    // Read Retry-After when supplied by the service.
    // Apply a bounded backoff before retrying.
    // Consider queueing the work instead of blocking the user.
end;

For high-volume integrations, use queues, batching, filtering, smaller payloads and controlled concurrency. Microsoft recommends retry strategies such as regular intervals, incremental intervals, exponential backoff and randomization for throttling scenarios.

Microsoft Learn: Working with API limits in Business Central

500, 503 and 504: server-side and timeout problems

5xx errors indicate that the server or an upstream service could not complete the request. A temporary 503 can be retried with backoff, but a 500 should also be investigated because repeated retries may simply reproduce the same failure.

A 504 Gateway Timeout is different: if the operation consistently takes too long, redesign the integration by splitting large requests, reducing the data returned, filtering earlier, or moving long-running work to an asynchronous pattern.

Microsoft Learn: Web service performance

Always check both HttpClient result and HTTP status

When calling an external API from AL, check whether the HTTP operation itself succeeded and then inspect the returned status code.

if not Client.Send(Request, Response) then
    Error('The HTTP request could not be completed.');

if not Response.IsSuccessStatusCode() then begin
    Response.Content().ReadAs(ResponseText);
    Error(
        'API failed. HTTP %1. Response: %2',
        Response.HttpStatusCode(),
        ResponseText);
end;

This distinction is important because HttpClient.Send can fail before a normal HTTP response is available, while a response such as 400 or 429 means the remote service did answer your request.

Microsoft Learn: HttpClient.Send

Build a reusable API error handler

For a larger extension, avoid duplicating the same status-code checks in every integration procedure. Centralize the response inspection and return a structured error or an ErrorInfo object to the calling code.

local procedure EnsureSuccess(Response: HttpResponseMessage)
var
    ResponseText: Text;
begin
    if Response.IsSuccessStatusCode() then
        exit;

    Response.Content().ReadAs(ResponseText);

    Error(
        'External API failed. HTTP %1. Response: %2',
        Response.HttpStatusCode(),
        ResponseText);
end;

In production code, consider logging the endpoint category, status code, correlation information and a sanitized response while avoiding access tokens, passwords and other secrets.

Using TryFunction for recoverable AL errors

For AL operations where an error should be handled by the caller instead of immediately stopping execution, a TryFunction can be useful. The result should be evaluated so the error is caught as intended.

[TryFunction]
local procedure CallExternalService(): Boolean
begin
    // Perform an operation that may raise an AL error.
end;

if not CallExternalService() then begin
    // Handle the failure and continue safely.
end;

Try methods are one part of AL error handling; they do not replace HTTP status-code handling. An API returning 401 or 429 is still an HTTP response that your integration should interpret explicitly.

Microsoft Learn: Handling errors using try methods

Production best practices

• Always check HTTP status codes.
• Read and sanitize error response bodies.
• Never log access tokens or secrets.
• Use exponential backoff for retryable 429/503 scenarios.
• Do not blindly retry validation errors such as most 400 responses.
• Use queues for high-volume or non-interactive integrations.
• Keep external API calls out of long-running interactive UI operations when possible.
• Record enough telemetry or application logging to diagnose failures.
• Test expired tokens, missing permissions, invalid payloads, missing records and throttling.
• Document which errors are retryable and which require manual intervention.

Quick troubleshooting decision tree

1. Did the AL HTTP call itself fail? Check URI, DNS, certificate, timeout and outbound HttpClient permission.
2. Did you receive an HTTP response? Read the status code.
3. 4xx? Correct the request, authentication, permissions, route or resource state.
4. 429? Back off and retry according to the service limits.
5. 5xx? Check service availability and retry only when appropriate.
6. 504 repeatedly? Redesign the request rather than increasing retries.
7. Still failing? Inspect telemetry, response details and the AL debugger.