Skip to main content
When an API request fails, the platform returns a structured error response with details about what went wrong. This section helps you diagnose and resolve common errors.

​
Understanding error responses

API errors return a JSON response with the following structure: 
{
  "type": "https://docs.narrative.io/reference/errors/...",
  "title": "Error Title",
  "status": 409,
  "detail": "Detailed explanation of what went wrong",
  "instance": "/api/endpoint",
  "logId": "unique-error-identifier"
}
FieldDescription
typeURL identifying the error type with resolution steps
titleBrief error summary
statusHTTP status code
detailDetailed explanation of the problem
instanceThe API endpoint that produced the error
logIdUnique identifier for support requests
When contacting support about an error, include the logId value to help quickly identify your specific issue.

​
Common errors

Access Rule, Table, or View Already Exists

Resolve HTTP 409 naming conflicts when creating access rules, datasets, or views

Dataset Schema Incompatible with Connector

Resolve HTTP 400 schema validation failures when connecting datasets to connectors

​
General troubleshooting steps

  1. Read the error detail — The detail field usually explains exactly what’s wrong
  2. Check the status code — Identifies the category of error (400 for validation, 409 for conflicts, etc.)
  3. Review your request — Look for the specific element mentioned in the error
  4. Check the type URL — Follow the link for detailed resolution steps