Error handling

Understand Navixy Repository API errors based on RFC 9457 format

Navixy Repository API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.

When an operation fails, the API returns an error response with details to help you understand what went wrong and how to fix it. All errors follow the RFC 9457 Problem Details format, providing both human-readable messages and machine-readable codes.

Error response structure

Errors are returned in the standard GraphQL format with additional details in the extensions field:

{
  "errors": [{
    "message": "Human-readable message",
    "locations": [{ "line": 2, "column": 3 }],
    "path": ["device"],
    "extensions": {
      // RFC 9457 standard fields
      "type": "https://api.navixy.com/errors/not-found",
      "title": "Resource Not Found",
      "status": 404,
      "detail": "Device with ID '019a6a3f-...' does not exist",
      "instance": "/graphql",
      
      // Navixy-specific fields
      "code": "NOT_FOUND",
      "entityType": "Device",
      "entityId": "019a6a3f-...",
      "traceId": "0af7651916cd43dd8448eb211c80319c",
      "timestamp": "2025-01-15T14:30:00.000Z"
    }
  }],
  "data": { "device": null }
}

Standard fields

Every error includes these RFC 9457 standard fields:

Field	Type	Description
type	URI	Identifies the error type. Resolves to documentation.
title	String	Summary of the problem type. Stays the same for all errors of this type.
status	Integer	HTTP status code (e.g., 400, 404, 409).
detail	String	Human-readable explanation specific to this occurrence of the problem.
instance	URI	The request path that caused the error. Useful for logs or support tickets.

Navixy-specific fields

Field	Description
code	Machine-readable error code for use in your application logic.
traceId	Distributed tracing ID (32 hex characters). Correlates with the traceparent header if provided.
timestamp	When the error occurred (ISO 8601 format).
field	For validation errors: the field that failed validation (e.g., input.title).
entityType	For entity-related errors: type of entity involved (e.g., Device).
entityId	For entity-related errors: ID of entity involved.
expectedVersion	For conflict errors: the version you provided.
currentVersion	For conflict errors: the actual current version.
constraint	For duplicate errors: the database constraint that was violated.
allowedValues	For enum validation errors: the list of valid options.

Error codes

Code	Status	Type URI	Description
UNAUTHORIZED	401	.../errors/unauthorized	Authentication is missing or invalid.
PERMISSION_DENIED	403	.../errors/forbidden	You don't have permission to perform this action.
NOT_FOUND	404	.../errors/not-found	The requested entity does not exist.
VALIDATION_ERROR	400	.../errors/validation	Input data failed validation.
CONFLICT	409	.../errors/conflict	The entity was modified by another request. See Optimistic locking.
DUPLICATE	409	.../errors/duplicate	A unique constraint was violated (e.g., duplicate identifier).
RATE_LIMITED	429	.../errors/rate-limited	Request limit exceeded. Wait and retry.
QUERY_TOO_COMPLEX	400	.../errors/query-too-complex	Query exceeds the allowed complexity limit.
QUERY_TOO_DEEP	400	.../errors/query-too-deep	Query exceeds the allowed nesting depth.
INTERNAL_ERROR	500	.../errors/internal	An internal error has occurred.
SERVICE_UNAVAILABLE	503	.../errors/service-unavailable	A downstream service is temporarily unavailable.

HTTP status codes

Navixy Repository API follows the GraphQL-over-HTTP specification, which means HTTP status codes reflect transport-level results, not domain-level errors.

HTTP Status	Meaning
200	Request processed successfully. Check the errors array for any domain-level failures.
400	Invalid HTTP or GraphQL request (parse or validation error).
401	Authentication required or invalid.
403	Authorization failed (forbidden).
429	Rate limit exceeded.
5xx	Infrastructure or system error.

All business logic errors (such as NOT_FOUND, CONFLICT, or VALIDATION_ERROR) return HTTP 200 with the semantic status code in extensions.status. Use extensions.code for programmatic error handling, not the HTTP status.

Common error scenarios

Validation error (400)

Returned when input data fails validation — for example, a required field is missing, a value is out of range, or a string exceeds the maximum length.

{
  "errors": [{
    "message": "Validation failed",
    "path": ["createDevice", "input", "title"],
    "extensions": {
      "type": "https://api.navixy.com/errors/validation",
      "title": "Validation Error",
      "status": 400,
      "detail": "Field 'title' must not be empty",
      "instance": "/graphql",
      "code": "VALIDATION_ERROR",
      "field": "title",
      "traceId": "0af7651916cd43dd8448eb211c80319c",
      "timestamp": "2025-01-15T14:30:00.000Z"
    }
  }]
}

How to handle: Check the field to identify which input failed, and detail for the specific requirement.

Permission denied (403)

Returned when you're authenticated but lack the required permission for the requested operation. Navixy Repository API uses role-based access control, so permissions depend on your assigned roles.

{
  "errors": [{
    "message": "Access denied",
    "path": ["deleteDevice"],
    "extensions": {
      "type": "https://api.navixy.com/errors/forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Actor lacks DELETE permission on device 550e8400-...",
      "instance": "/graphql",
      "code": "PERMISSION_DENIED",
      "entityType": "device",
      "entityId": "550e8400-e29b-41d4-a716-446655440001",
      "requiredAction": "DELETE",
      "traceId": "0af7651916cd43dd8448eb211c80319c",
      "timestamp": "2025-01-15T14:30:00.000Z"
    }
  }]
}

How to handle: The requiredAction tells you what permission is needed. Contact your administrator to request access.

Entity not found (404)

Returned when the requested entity doesn't exist, has been deleted, or belongs to an organization you don't have access to.

{
  "errors": [{
    "message": "Device not found",
    "path": ["device"],
    "locations": [{ "line": 1, "column": 9 }],
    "extensions": {
      "type": "https://api.navixy.com/errors/not-found",
      "title": "Resource Not Found",
      "status": 404,
      "detail": "Device with ID '019a6a3f-793e-807b-8001-555345529b44' does not exist",
      "code": "NOT_FOUND",
      "entityType": "Device",
      "entityId": "019a6a3f-793e-807b-8001-555345529b44",
      "traceId": "0af7651916cd43dd8448eb211c80319c"
    }
  }],
  "data": { "device": null }
}

How to handle: Check that the ID is correct. If you're using an ID from a previous response, the entity may have been deleted.

Version conflict (409)

Returned when the entity was modified by another request since you last fetched it. See Optimistic locking for details.

{
  "errors": [{
    "message": "Entity has been modified by another request",
    "path": ["updateDevice"],
    "extensions": {
      "type": "https://api.navixy.com/errors/conflict",
      "title": "Conflict",
      "status": 409,
      "detail": "Device 550e8400-... was modified. Expected version 5, current version 6.",
      "instance": "/graphql",
      "code": "CONFLICT",
      "entityType": "device",
      "entityId": "550e8400-e29b-41d4-a716-446655440001",
      "expectedVersion": 5,
      "currentVersion": 6,
      "traceId": "0af7651916cd43dd8448eb211c80319c",
      "timestamp": "2025-01-15T14:30:00.000Z"
    }
  }]
}

How to handle: Fetch the entity again to get the current version, merge your changes if needed, and retry with the new version in your update input.

Duplicate (409)

Returned when you try to create or update an entity with a value that must be unique but already exists, such as a device identifier, user email, or catalog item code.

{
  "errors": [{
    "message": "Duplicate device identifier",
    "path": ["deviceCreate"],
    "extensions": {
      "type": "https://api.navixy.com/errors/duplicate",
      "title": "Duplicate Entry",
      "status": 409,
      "detail": "A device with identifier 'IMEI:123456789012345' already exists",
      "instance": "/graphql",
      "code": "DUPLICATE",
      "entityType": "Device",
      "constraint": "device_identifier_unique",
      "traceId": "0af7651916cd43dd8448eb211c80319c",
      "timestamp": "2025-01-15T14:30:00.000Z"
    }
  }]
}

How to handle: The constraint field indicates which uniqueness rule was violated. Either use a different value or query for the existing entity if you need to update it instead.

Best practices

1. Always check for errors. Inspect the errors array in every response, even when the HTTP status is 200 (GraphQL can return partial data with errors).

2. Use code for logic, detail for display. The code field is stable and safe for programmatic handling. The detail field is human-readable and suitable for showing to users.

3. Log the traceId. When users report issues, trace ID helps the support quickly locate the relevant logs. Include it in your bug reports.

4. Handle conflicts gracefully. In collaborative applications, version conflicts are expected. Implement retry logic or prompt users to review changes.