Errors

The Fegura API uses standard HTTP status codes and returns consistent JSON error responses. This page documents the error format and common error codes.

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": []
  }
}

Error Fields

Field	Type	Description
`success`	`boolean`	Always `false` for error responses
`error.code`	`string`	Machine-readable error code for programmatic handling
`error.message`	`string`	Human-readable description of the error
`error.details`	`array \| undefined`	Validation error details (present on Zod validation failures)

HTTP Status Codes

The API uses standard HTTP status codes to indicate request outcomes:

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions or scope
404	Not Found	Resource doesn't exist
409	Conflict	Resource conflict (e.g., duplicate)
500	Internal Server Error	Something went wrong on our end

Error Codes

Use the error.code field to programmatically handle specific error conditions:

Code	HTTP	Description
`UNAUTHORIZED`	401	API key is missing, invalid, or expired
`FORBIDDEN`	403	API key doesn't have required scope
`NOT_FOUND`	404	Requested resource doesn't exist
`BAD_REQUEST`	400	Malformed request or invalid parameters
`VALIDATION_ERROR`	400	Request body or parameters failed validation
`CONFLICT`	409	Resource already exists or conflicts with current state
`INVALID_API_VERSION`	400	The Fegura-Version header contains an unrecognized version
`INTERNAL_ERROR`	500	Server error; contact support if persistent

Error Handling Examples

Validation Error

// Request with invalid region
POST /api/scans
{
  "awsAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "region": "invalid-region"
}

// Response (400)
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "path": ["region"],
        "message": "Invalid region. Must be a valid AWS region code."
      }
    ]
  }
}

Resource Not Found

// Request for non-existent resource
GET /api/accounts/550e8400-e29b-41d4-a716-000000000000

// Response (404)
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "AWS Account not found"
  }
}

Best Practices

Check success first - Always check the success field before processing response data.
Handle errors by code - Use error.code for programmatic handling, not the message text.
Implement retries - For 5xx errors, implement exponential backoff with jitter.
Log errors - Log the full error response for debugging, including request ID if available.
Show user-friendly messages - Use error.message for user-facing error displays.