Solve Data API Builder Issues: A Practical Troubleshooting Guide for Azure

Table of Contents

Data API builder for Azure databases serves as a bridge, securely exposing your database assets (tables, views, stored procedures) as modern REST and GraphQL endpoints. While powerful, configuring and running Data API builder can sometimes lead to errors. This guide provides practical solutions to common issues you might encounter, helping you diagnose and resolve problems efficiently when working with Data API builder in Azure environments. Understanding the nature of these errors and their potential causes is the first step towards a stable and reliable data API.

Generic Endpoint: HTTP 400 “Bad Request” Error¶

An HTTP 400 “Bad Request” error is a client-side error indicating that the request sent to the server is somehow incorrect or corrupted, and the server cannot process it. In the context of Data API builder, this error often points to issues with the request’s structure, particularly regarding the endpoint paths or configuration mismatches. Let’s explore some specific scenarios that trigger this error.

Invalid Data API Builder Endpoint¶

Data API builder is configured with specific root paths for its REST and GraphQL services. These paths are defined in the runtime configuration file and dictate the base URL segments that Data API builder listens on for incoming requests. If an incoming request’s URL path does not correctly begin with the configured root path for the targeted endpoint (REST or GraphQL), Data API builder will deem it a malformed request, resulting in the HTTP 400 error.

The runtime section of your Data API builder configuration file is where these critical path settings reside. Within the rest and graphql subsections, you define the path property. This path value becomes the mandatory prefix for all requests directed at that specific endpoint. For instance, setting the REST path to /api means any valid REST request must start with /api/. Similarly, a GraphQL path of /graphql requires all GraphQL requests to start with /graphql.

Consider the following configuration snippet:

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

Based on this configuration, if you have an entity named products, the correct URL structure for interacting with the REST endpoint would be /api/products. Attempting to access it via /rest/products or just /products would result in the HTTP 400 error because the base path /api was not included. For the GraphQL endpoint, the standard path for submitting queries or mutations would be /graphql, following the path defined. Ensure your client applications or testing tools are configured to use these exact paths.

Static Web Apps Database Connections Configuration Issue¶

When integrating Data API builder with Azure Static Web Apps’ Database Connections feature, you might encounter a specific HTTP 400 “Bad Request” error within the response body, often accompanied by a message like:

{"Message":"{\"Message\":\"Response status code does not indicate success: 400 (Bad Request).\",\"ActivityId\":\"<GUID>\"}","ActivityId":"<GUID>"}

This nested error structure is indicative of a problem occurring during the communication between the Static Web Apps environment and your database, orchestrated by Data API builder behind the scenes. The underlying cause is frequently related to how the database connection itself is configured within the Static Web Apps portal or the database’s own network settings. It signifies that while the request reached Data API builder via Static Web Apps, DAB could not successfully establish a connection to the database using the provided credentials or network configuration.

To troubleshoot and resolve this issue, begin by verifying the database credentials you provided when linking the database in Static Web Apps. Use standard database tools like Azure Data Studio, SQL Server Management Studio (SSMS) for SQL databases, or MongoDB Compass for Cosmos DB (MongoDB API) to directly connect to your database using the exact username, password, and server details. This step confirms whether the credentials themselves are valid and the database is accessible from a typical client. If direct connection fails, the issue lies squarely with the database credentials or basic network access.

If the credentials are valid, the next step is often to unlink the database connection from your Static Web App and then relink it. This process can refresh the connection string and configuration used by Static Web Apps and Data API builder, sometimes resolving transient configuration glitches. Navigate to the Database Connections section in your Static Web App resource in the Azure portal to perform this unlink and relink action.

If the problem persists after verifying credentials and relinking, the issue might be related to database firewall settings. For Azure SQL Database or Azure Database for MySQL/PostgreSQL, you need to ensure that the server allows connections from Azure services. This setting is typically found in the “Networking” or “Connection security” section of your database server resource in the Azure portal. Look for an option like “Allow Azure services and resources to access this server” and ensure it is enabled. This permits connections originating from the Azure backbone network, which is how Static Web Apps and Data API builder typically connect to your database. Without this exception, the database firewall blocks the connection attempt, leading to the 400 error reported back through Static Web Apps.

Adding a diagram showing the connection flow via SWA and the database firewall:

mermaid graph LR A[Client Browser] --> B(Azure Static Web App); B --> C(Data API Builder Instance); C --> D{Database Firewall}; D --> E[Azure Database]; D --Blocked by Firewall--> C; subgraph Static Web App Integration B C end
This diagram illustrates how the request flows through Static Web Apps to Data API Builder, which then attempts to connect to the database. The database firewall acts as a gatekeeper, and if not configured correctly (e.g., allowing Azure services), it will block the connection from Data API Builder, causing the error.

REST Endpoint: HTTP 404 “Not Found” Error¶

An HTTP 404 “Not Found” error signifies that the server could not find a resource matching the requested URL. In the context of Data API builder’s REST endpoint, this error typically means that the URL path requested by the client does not correspond to any configured entity or a valid REST route defined in your Data API builder configuration. The error is not about permissions or a malformed request structure (like 400), but simply that the target resource identifier (the URL path) is unknown to Data API builder.

By default, Data API builder constructs the REST route for an entity using the entity’s name as defined in the configuration file. If you define an entity with the name Book in your configuration, Data API builder automatically makes it accessible via a REST path that includes /Book (case-sensitive by default, unless specifically configured otherwise in the runtime settings). For example, if your REST base path is /api and you have an entity named Product:

"Product": {
    "source": "dbo.products",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        }
    ]
    // ... other entity settings
}

The default REST route for this entity would be /api/Product. A request to /api/Product would be valid (assuming authentication/authorization allows it), while a request to /api/product (lowercase) or /api/Products (plural) would result in a 404 error because Data API builder is looking for a resource exactly named Product at that path segment.

However, you have the flexibility to customize the REST path for each entity using the rest.path property within the entity’s configuration. This allows you to decouple the internal entity name from the external-facing URL segment. If you set rest.path for the Product entity to items:

"Product": {
    "source": "dbo.products",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        }
    ],
    "rest": {
        "path": "items",
        "enabled": true // enabled by default unless set to false
    }
    // ... other entity settings
}

In this case, the Product entity is only reachable via the custom path /api/items. Requests to the default /api/Product path will now return a 404 error because that route is no longer active for this entity. The value specified in rest.path is used exactly as provided, including its casing.

Therefore, when troubleshooting a 404 error on the REST endpoint, carefully check:
1. Does the requested URL path start with the correct global REST base path (e.g., /api)?
2. Does the segment following the base path exactly match either the entity name or the rest.path value configured for that entity? Pay close attention to casing, as routes are case-sensitive unless your runtime configuration specifies otherwise (which is not a common default).

A quick reference table for route mapping might be helpful:

Entity Name	rest.path Configured?	rest.path Value	Default REST Route (assuming /api base)	Custom REST Route (if rest.path exists)	Valid Routes
Orders	No	N/A	/api/Orders	N/A	/api/Orders
Customers	Yes	"clients"	/api/Customers (disabled)	/api/clients	/api/clients
Details	Yes	"details"	/api/Details (disabled)	/api/details	/api/details

If you are still facing issues, double-check your Data API builder configuration file for typos in entity names or rest.path values and ensure the file being used by the running Data API builder instance is the one you expect.

GraphQL Endpoint: HTTP 400 “Bad Request” Error¶

Similar to the REST endpoint, an HTTP 400 “Bad Request” error on the GraphQL endpoint indicates an issue with the client’s request structure itself. However, the nature of GraphQL requests differs significantly from REST. GraphQL requests are typically sent as a single query or mutation string within the request body. A 400 error in this context usually means the GraphQL payload is syntactically incorrect, refers to non-existent types or fields, or violates the GraphQL specification in some way that prevents Data API builder from parsing and executing the request.

Common causes for a GraphQL 400 error include:
* Syntactical errors in the GraphQL query or mutation string (e.g., missing braces, commas, or incorrect field aliases).
* Referencing an entity name that is not exposed via GraphQL or is misspelled.
* Referencing a field name within an entity that does not exist in the underlying database table/view or is not exposed by Data API builder.
* Using the wrong operation type (e.g., trying to perform a mutation with a query keyword).

Data API builder is designed to provide helpful feedback in these situations. When a GraphQL request fails due to an invalid query structure or content, the response payload typically includes a detailed errors array, conforming to the GraphQL specification for error reporting. This array contains messages indicating exactly what went wrong, often pinpointing the location within the query string that caused the error. Always examine the response body for these detailed error messages when you receive a GraphQL 400.

A particularly common reason for a GraphQL 400 error, specifically when using the HTTP GET method, is attempting to pass the query parameters incorrectly. While the GraphQL specification allows for GET requests with the query in the URL query string, Data API builder primarily expects GraphQL requests to be sent using the HTTP POST method. The GraphQL query or mutation should be included in the request body, typically as a JSON object with a "query" key (and optional "variables" and "operationName" keys).

If you send a GET request to the GraphQL endpoint without correctly structuring the query in the URL parameters according to the specific format Data API builder expects (which is less common and more error-prone than POST), you will likely receive a 400 error with a message similar to: “Either the parameter query or the parameter ID has to be set.” This clearly indicates that Data API builder couldn’t find the expected query parameter in the GET request format it understands. Always use HTTP POST for your GraphQL queries and mutations with the query string in the JSON body to avoid this specific 400 error and ensure compatibility with standard GraphQL tooling.

Here is an example of a correctly structured GraphQL POST request body:

{
  "query": "query GetProducts { products { id name price } }",
  "variables": {} // Optional
}

And a correctly structured mutation POST request body:

{
  "query": "mutation CreateProduct($name: String!, $price: Int!) { createProduct(item: { name: $name, price: $price }) { id name } }",
  "variables": {
    "name": "New Gadget",
    "price": 100
  }
}

Ensure your client, whether it’s a custom application or a tool like Insomnia or Postman, is configured to send a POST request with the Content-Type header set to application/json and the GraphQL payload correctly formatted in the request body.

GraphQL Endpoint: HTTP 404 “Not Found” Error¶

An HTTP 404 “Not Found” error specifically on the GraphQL endpoint is less common than a 400, but it can occur. This error means that the server could not find the GraphQL endpoint itself at the requested URL path. It’s not an error about the GraphQL query being malformed (that would be a 400), but rather that the entry point for GraphQL processing wasn’t found where the client expected it.

The primary cause of a GraphQL 404 error is attempting to access the endpoint at a URL path that does not match the one configured in your Data API builder’s runtime settings. By default, Data API builder sets the GraphQL endpoint path to /graphql. This is defined in the runtime.graphql.path property of your configuration file.

Verify the path setting in the runtime.graphql section of your configuration:

"runtime": {
    // ... other settings
    "graphql": {
      "enabled": true,
      "path": "/graphql", // Check this value
      "allow-introspection": true
    }
    // ... other settings
}

Ensure that the URL you are sending the GraphQL request to exactly matches this configured path, relative to the root of your Data API builder instance. For example, if your DAB instance is hosted at https://mydabinstance.azurewebsites.net, and the GraphQL path is set to /graphql, your requests should go to https://mydabinstance.azurewebsites.net/graphql.

Also, double-check that the GraphQL endpoint is actually enabled in the configuration ("enabled": true). If "enabled" is set to false, the GraphQL endpoint will not be active, and any attempt to access its path will result in a 404 “Not Found” error.

Remember, GraphQL requests should typically use the HTTP POST method. While the 404 error is about the path, ensure your tool or code is also using the correct method, as some servers might respond differently (though typically a method issue would be a 405 Method Not Allowed, a misconfigured endpoint might return 404 for any method). Focus initially on confirming the requested URL path matches the configured runtime.graphql.path.

GraphQL Endpoint: “The object type Query has to at least define one field in order to be valid” Error¶

This specific error message, “The object type Query has to at least define one field in order to be valid,” is a validation error during the startup phase of Data API builder. It means that Data API builder failed to generate a valid GraphQL schema based on your provided runtime configuration. The GraphQL specification requires that a valid schema must include a Query type, and this Query type must expose at least one field that clients can query. If Data API builder cannot define any queryable fields based on your configuration, it cannot build a valid schema and thus fails to start, displaying this error.

This issue arises when your configuration does not expose any data or operations that can be represented as query fields in the GraphQL schema. This can happen in two main scenarios:

1. No entities with read action enabled for GraphQL: Data API builder automatically creates GraphQL query fields for entities where the read action is permitted for at least one role. By default, all entities are enabled for GraphQL unless you explicitly disable it by setting graphql.enabled to false for that entity. If all your configured entities either have graphql.enabled: false or have no roles granted the read permission (actions: [ "read" ]), Data API builder won’t be able to generate any query fields for these entities. Ensure at least one entity has graphql.enabled set to true (or is not set, defaulting to true) and has the read action allowed for a role that will be used to access the GraphQL endpoint (e.g., anonymous or authenticated).

   Example of an entity configuration that would contribute a read field (assuming graphql.enabled is true or default):
   

   "Book": {
     "source": "dbo.books",
     "permissions": [
       {
         "role": "anonymous",
         "actions": [ "read" ] // This enables a 'query' field like 'books' or 'book_by_pk'
       },
       {
         "role": "authenticated",
         "actions": [ "create", "update", "delete" ]
       }
     ]
     // graphql is true by default
   }
   

   
   Example of an entity configuration that would NOT contribute a read field:
   

    "SensitiveData": {
     "source": "dbo.sensitive_data",
     "permissions": [
       {
         "role": "admin",
         "actions": [ "create", "update", "delete" ] // No read action granted
       }
     ],
     "graphql": { "enabled": true } // GraphQL is enabled, but no read fields possible for any role
   }
   

   
   Or:
   

    "InternalTable": {
     "source": "dbo.internal_table",
     "permissions": [
        // permissions defined, but none allow read
     ],
     "graphql": { "enabled": false } // GraphQL explicitly disabled for this entity
   }
   

   
   At least one entity like Book must exist in your configuration to satisfy the GraphQL schema requirement for a Query type.

2. Only Stored Procedures exposed, and none configured as query operation: Data API builder can expose stored procedures via GraphQL. By default, stored procedures are treated as mutation operations because they often involve data modification. If your configuration only exposes stored procedures, and you don’t explicitly override the default operation type for at least one stored procedure to be a query, Data API builder will generate a schema with only mutation fields and no query fields. This again leads to the schema validation error.

   To resolve this when using only stored procedures, you must identify at least one stored procedure that performs a read-only operation (it should not modify data) and configure its graphql.operation property to query:

   "GetCustomerList": {
     "source": "dbo.get_customer_list",
     "source.type": "stored-procedure",
     "permissions": [
       {
         "role": "anonymous",
         "actions": [ { "action": "execute" } ]
       }
     ],
     "graphql": {
       "enabled": true, // true by default, but good to be explicit
       "operation": "query" // **Crucial setting to make it a query field**
     }
   }
   

   
   If you have other stored procedures that modify data, they can remain with the default mutation operation type or explicitly set "operation": "mutation". But at least one must be configured with "operation": "query" to satisfy the schema requirement. Important: The stored procedure configured as a query must genuinely be read-only. Configuring a stored procedure that modifies data as a query operation might have unintended side effects or be disallowed by the database depending on the operation.

In summary, to fix the “The object type Query has to at least define one field” error, review your Data API builder configuration and ensure that either you have at least one standard entity with the read action allowed and GraphQL enabled, OR you have at least one stored procedure entity explicitly configured with "graphql": { "operation": "query" }.

GraphQL Endpoint: Introspection Doesn’t Work with the GraphQL Endpoint¶

GraphQL introspection is a powerful feature that allows clients and tools (like GraphQL playgrounds, IDEs, or schema stitching services) to query the GraphQL schema itself. This is how tools can provide features like autocomplete, validation, and schema visualization. By default, Data API builder has GraphQL introspection disabled for security reasons in a production environment. If you are developing or testing and your GraphQL tools cannot fetch the schema, introspection is likely disabled.

To enable GraphQL introspection, you need to modify the runtime.graphql section of your Data API builder configuration and set the allow-introspection property to true.

"runtime": {
    // ... other settings
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true // **Set this to true**
    }
    // ... other settings
}

After changing this setting, restart your Data API builder instance for the configuration change to take effect. Once enabled, your GraphQL tools should be able to connect to the /graphql endpoint (or your custom path) and fetch the schema metadata, enabling features like exploring available types, fields, arguments, and documentation directly from the live endpoint. Remember the security implications of enabling introspection in a production environment and consider disabling it or restricting access to it if necessary.

GraphQL Endpoint: “The mutation operation was successful but the current user is unauthorized to view the response due to lack of read permissions” Error¶

This is a specific and informative error message that Data API builder returns for GraphQL mutation operations (like create, update, delete). It indicates a two-stage process:
1. The mutation successfully executed against the backend database. Data was created, updated, or deleted as requested.
2. However, after the database operation succeeded, Data API builder attempted to fetch the result of the mutation (e.g., the newly created item, the updated item’s new state, or confirmation of deletion) to include in the GraphQL response payload as requested by the query projection. At this point, Data API builder checked the permissions for the read action on that specific entity for the role associated with the current user, and found that the user’s role does not have read permissions. Because DAB cannot read the data to construct the successful response payload, it returns this error instead, confirming the database operation succeeded but denying the user the ability to see the result.

This situation most commonly occurs when you have configured permissions for a role to create, update, or delete on an entity, but not read. For a GraphQL mutation to return the details of the affected item in the response payload, the user’s role must have read permissions on that entity in addition to the specific mutation permission.

To resolve this, identify the entity and the role the user is operating under (either the anonymous role, the default authenticated role, or a custom role specified via the X-MS-API-ROLE header). Then, modify the permissions configuration for that entity and role to include the read action.

For example, if you have a products entity and a manager role is getting this error when creating products:

"Product": {
    "source": "dbo.products",
    "permissions": [
      {
        "role": "anonymous", // Or 'authenticated' or your custom role
        "actions": [ "read" ] // Add or ensure 'read' is included here
      },
      {
        "role": "manager",
        "actions": [ "create", "update", "delete", "read" ] // Ensure 'read' is also here for mutations to return data
      }
    ]
    // ...
}

By adding the read action to the role’s permissions for the entity, you allow Data API builder to fetch and return the data associated with the successful mutation operation. If you do not want users in a specific role to be able to query the entity directly, but only see the result of their mutations, you might need a more complex permission setup, but granting read is the standard way to enable mutation result payloads. Alternatively, if you truly don’t want the user to see the result of the mutation (e.g., for security or privacy), you could structure the GraphQL mutation query to not request any fields in the response payload (though the default DAB behavior expects fields). The most straightforward solution is to grant the necessary read permission.

General Error: HTTP 500 Error Returned by Requests¶

An HTTP 500 “Internal Server Error” is a generic server-side error. In the context of Data API builder, it indicates that DAB encountered an unexpected condition or failure while trying to process a request, preventing it from returning a more specific error code. This often points to issues occurring between Data API builder and the backend database, or problems with Data API builder’s internal state or configuration that cause a runtime crash.

Common causes for HTTP 500 errors include:
* Database connectivity issues: Data API builder cannot connect to the configured database using the provided connection string or credentials. This could be due to incorrect credentials, database server being down, network issues, or firewall blocks (different from the Static Web Apps specific 400, this is DAB failing to connect directly).
* Database object accessibility: The underlying database table, view, or stored procedure that an entity is mapped to does not exist, is misspelled in the configuration, or the database user Data API builder is using does not have sufficient permissions to access it.
* Malformed database response: The database returned data in an unexpected format that Data API builder could not process, potentially due to schema drift or complex data types not handled correctly.
* Internal Data API builder configuration errors: Although less common after a successful startup, certain configurations could lead to runtime failures under specific request patterns.

To effectively troubleshoot HTTP 500 errors with Data API builder, the most critical step is to gain visibility into the actual error occurring on the server side. Data API builder provides detailed logging to help with this, controlled by the runtime.host.mode setting in your configuration.

By default, Data API builder runs in production mode ("runtime": { "host": { "mode": "production" } }). In this mode, detailed error information is suppressed in the HTTP response body for security reasons. The client only receives a generic 500 status code. However, Data API builder always writes detailed error information to its console or logs when running in either production or development mode. Check the console output where you are running Data API builder (e.g., your local terminal, the Azure Container App logs, the Azure Web App logs, etc.). The detailed error messages in the logs are invaluable for diagnosing the root cause, often including database-specific error codes or stack traces.

For development and testing environments, you can set the runtime.host.mode configuration property to development:

"runtime": {
    // ... other settings
    "host": {
        "mode": "development", // Set to 'development' for detailed errors in response
        // ... other host settings
    }
    // ... other settings
}

When running in development mode, Data API builder includes more detailed error information directly in the HTTP response payload received by the client. This can significantly speed up troubleshooting as you don’t need to immediately check the server logs for every error. However, never run Data API builder in development mode in a production environment as it can expose sensitive details about your database or application internals to clients.

Regardless of the mode, always:
1. Check Data API builder logs/console output: This is the primary source of detailed error information.
2. Verify database connectivity and credentials: Ensure Data API builder can successfully authenticate and connect to the database.
3. Check database user permissions: The user configured for Data API builder needs appropriate SELECT, INSERT, UPDATE, DELETE, or EXECUTE permissions on the specific tables, views, or stored procedures being exposed.
4. Verify database object names: Double-check that the source property in your entity configurations accurately matches the names of tables, views, or stored procedures in your database, including casing.

By combining checking the detailed logs (and temporarily using development mode if appropriate for troubleshooting) with verifying your database setup, you should be able to pinpoint the cause of the 500 error.

General Errors Due to Unauthenticated and Unauthorized Requests¶

Authentication and authorization are critical security layers. Data API builder supports various authentication providers and implements a flexible role-based authorization model. Misconfigurations or incorrect usage of these features commonly result in HTTP 401 “Unauthorized” or HTTP 403 “Forbidden” errors. Understanding the distinction between these two is key to troubleshooting.

Authentication (401 Unauthorized): The server doesn’t know who you are. You haven’t provided valid credentials or identification to prove your identity.
Authorization (403 Forbidden): The server knows who you are (you are authenticated), but you are not allowed to access the requested resource or perform the requested action based on your identity and assigned roles.

HTTP 401 “Unauthorized” Error¶

An HTTP 401 “Unauthorized” error from Data API builder means the request failed the authentication step. Data API builder requires authentication for any endpoint or entity configured with roles other than “anonymous” that require proof of identity. If you send a request that requires authentication but fail to provide any credentials, or provide credentials that Data API builder cannot validate, you will receive a 401 error.

When using Microsoft Entra ID (formerly Azure Active Directory) authentication with Data API builder, a 401 error almost always means the bearer token (Access Token) provided in the Authorization: Bearer <token> header is invalid or missing. Bearer tokens are JWTs (JSON Web Tokens) and their validity is determined by several factors:

• Expiration: The token’s validity period has passed.
• Audience (Aud): The token was issued for a different resource or application than your Data API builder instance. The aud claim in the token must match the expected audience configured in Data API builder.
• Issuer (Iss): The token was not issued by the expected authority. The iss claim in the token must match the expected issuer configured in Data API builder.
• Signature Validation: The token’s signature is invalid, indicating it might have been tampered with or the wrong signing key was used.

Your Data API builder configuration specifies the expected issuer and audience for Microsoft Entra ID tokens in the authentication.jwt section:

"authentication": {
    "provider": "AzureAD", // Or "StaticWebApps"
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/", // Tenant ID in the path
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3" // Application (Client) ID of your DAB registration
    }
    // ... other authentication settings
}

To resolve 401 errors with Microsoft Entra ID:
1. Verify the Access Token: Ensure your client is sending a bearer token in the Authorization header.
2. Check Token Validity: Use a tool like jwt.ms to paste your access token and inspect its claims. Verify that the iss claim matches the configured issuer and the aud claim matches the configured audience.
3. Generate Token Correctly: When acquiring the token (e.g., using MSAL libraries, Azure CLI, or Azure AD endpoints), ensure you are requesting the token for the correct scope or resource that corresponds to your Data API builder’s configured audience (which is typically the Application ID URI or the Application (Client) ID itself).

Using Azure CLI, you can acquire a token for a specific resource/audience like this:

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3" --tenant "24c24d79-9790-4a32-bbb4-a5a5c3ffedd5"

Replace the GUIDs with your specific tenant ID and Data API builder application’s client ID/audience URI.

If you are using Static Web Apps authentication ("provider": "StaticWebApps"), the 401 error indicates that the request did not come through the Static Web Apps environment with a valid authentication header (X-MS-CLIENT-PRINCIPAL). Ensure your client is accessing Data API builder via the Static Web App frontend, not directly.

HTTP 403 “Forbidden” Error¶

An HTTP 403 “Forbidden” error occurs when Data API builder successfully authenticates the request (it knows who the user is) but determines that the authenticated user’s assigned roles do not have permission to perform the requested action on the target entity. Authorization failures happen after authentication succeeds.

Data API builder uses role-based access control defined in the permissions section of each entity configuration. Requests are evaluated against these rules based on the role the request is operating under.

Troubleshooting 403 errors involves checking:
1. The User’s Role(s):
* For Microsoft Entra ID, user roles are typically embedded in the access token (e.g., in the roles or wids claims). Data API builder evaluates the request against these roles.
* For Static Web Apps, roles come from the X-MS-CLIENT-PRINCIPAL header.
* If no specific role is specified by the client (via X-MS-API-ROLE) and the user is authenticated, the request runs under the implicit authenticated system role.

2. The X-MS-API-ROLE Header: If the user intends to use a specific custom role (not anonymous or authenticated), they must include the X-MS-API-ROLE HTTP header in the request with the exact name of the desired role as its value. Role names are case-sensitive.

3. Role Definition in Configuration: The role name specified in the X-MS-API-ROLE header (or implicitly used) must exactly match a role name defined in the permissions section of the relevant entity configuration. If the role name in the header doesn’t exist in the configuration for that entity, Data API builder doesn’t know how to authorize the request under that role, leading to a 403.

4. Permissions for the Role and Action: For the specific role being used, check the actions array within the permissions section for the target entity. The array must include the specific action being attempted (e.g., "read", "create", "update", "delete", or "execute" for stored procedures). If the action is not listed for that role, the request is forbidden.

Example entity permission configuration:

"Order": {
    "source": "sales.orders",
    "permissions": [
        {
            "role": "anonymous", // Anonymous users cannot read Orders by default
            "actions": []
        },
        {
            "role": "authenticated", // Authenticated users can read their own orders
            "actions": [ { "action": "read", "policy": { "request": "..." } } ]
        },
        {
            "role": "manager", // Managers can read all orders and update some fields
            "actions": [ "read", { "action": "update", "fields": ["status", "deliveryDate"] } ]
        }
    ]
    // ...
}

In this example:
* An anonymous user trying to read an order gets a 403 because read is not allowed for anonymous.
* An authenticated user trying to update an order gets a 403 because update is not allowed for authenticated.
* A user with the manager role trying to update the orderDate field gets a 403 because only status and deliveryDate are allowed for update.
* An authenticated user including X-MS-API-ROLE: manager but whose access token does not contain the manager role claim gets a 403 because the requested role doesn’t match their identity.

When troubleshooting 403 errors, confirm the user is authenticated correctly, check if an X-MS-API-ROLE header is used (and its value is correct and case-sensitive), verify that the role exists in the entity’s permissions configuration, and finally, ensure the specific action is listed in the actions for that role.

Conclusion¶

Troubleshooting Data API builder issues involves systematically checking configurations, request formats, authentication credentials, authorization rules, and database connectivity. By understanding the common error codes (400, 401, 403, 404, 500) and their specific meanings within the Data API builder context, you can quickly narrow down the potential causes. Leveraging detailed logging (especially by temporarily using development mode in non-production environments) is crucial for diagnosing backend database interaction issues. Remember to pay close attention to endpoint paths, required HTTP methods, entity names, case sensitivity, role definitions, and permission grants in your Data API builder configuration file.

If you encounter an issue not covered here or require further assistance, the Data API builder community and official resources are valuable assets. Have you faced similar challenges or found alternative solutions? Share your experiences in the comments below!