Error Handling

The EntryGuard API uses conventional HTTP status codes to indicate the success or failure of requests. Errors include detailed information to help you diagnose and fix issues.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/auth/register",
  "validationErrors": {
    "email": "must not be blank",
    "password": "size must be between 8 and 128"
  }
}

Response Fields

Field	Type	Description
timestamp	string	ISO 8601 timestamp when the error occurred (UTC)
status	integer	HTTP status code
error	string	HTTP status text (e.g., "Bad Request", "Unauthorized")
message	string	Human-readable error description
path	string	API endpoint path where the error occurred
validationErrors	object	Field-level validation errors (only present for 400 errors)

HTTP Status Codes

200 OK

The request succeeded. The response body contains the requested data.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production Database",
  "status": "ACTIVE"
}

201 Created

A new resource was successfully created. The response body contains the created resource.

Example: Creating a resource

curl -X POST https://api.entryguard.io/api/v1/resources \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Database",
    "provider": "AWS",
    "credentialId": "550e8400-e29b-41d4-a716-446655440000",
    "config": {
      "securityGroupId": "sg-0123456789abcdef0",
      "region": "us-east-1"
    }
  }'

Response: 201 Created

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production Database",
  "provider": "AWS",
  "createdAt": "2024-01-15T10:30:00Z"
}

204 No Content

The request succeeded and there is no response body. Commonly used for DELETE operations.

Example: Deleting a resource

curl -X DELETE https://api.entryguard.io/api/v1/resources/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content (empty body)

400 Bad Request

The request was invalid or contains incorrect parameters. Check the message and validationErrors fields for details.

Common Causes

• Missing required fields
• Invalid field values
• Failed validation constraints
• Malformed JSON

Example: Invalid registration

curl -X POST https://api.entryguard.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "",
    "email": "invalid-email",
    "password": "short"
  }'

Response: 400 Bad Request

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/auth/register",
  "validationErrors": {
    "organizationName": "must not be blank",
    "email": "must be a well-formed email address",
    "password": "size must be between 8 and 128"
  }
}

Example: Business logic error

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Maximum number of users (10) reached for your organization",
  "path": "/api/v1/users"
}

401 Unauthorized

Authentication failed or the token is missing, expired, or invalid.

Common Causes

• Missing Authorization header
• Expired access token
• Invalid JWT signature
• Invalid API key

Example: Missing token

curl -X GET https://api.entryguard.io/api/v1/sessions

Response: 401 Unauthorized

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "path": "/api/v1/sessions"
}

Example: Expired token

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Token has expired",
  "path": "/api/v1/sessions"
}

Resolution

Use POST /auth/refresh with your refresh token to obtain a new access token:

curl -X POST https://api.entryguard.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token-here"
  }'

403 Forbidden

The authenticated user does not have permission to perform this action.

Common Causes

• Insufficient role (e.g., regular user trying to access admin endpoint)
• API key with insufficient scope
• Attempting to modify resources you don't own

Example: Non-admin accessing admin endpoint

curl -X GET https://api.entryguard.io/api/v1/users \
  -H "Authorization: Bearer USER_TOKEN"

Response: 403 Forbidden

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied. Administrator privileges required.",
  "path": "/api/v1/users"
}

Example: API key scope error

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 403,
  "error": "Forbidden",
  "message": "API key does not have access to this resource",
  "path": "/api/v1/credentials"
}

404 Not Found

The requested resource does not exist or belongs to a different organization.

Common Causes

• Invalid resource ID
• Resource was deleted
• Resource belongs to another organization (multi-tenant isolation)

Example: Non-existent resource

curl -X GET https://api.entryguard.io/api/v1/resources/99999999-9999-9999-9999-999999999999 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 404 Not Found

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 404,
  "error": "Not Found",
  "message": "Resource not found",
  "path": "/api/v1/resources/99999999-9999-9999-9999-999999999999"
}

Note on Multi-Tenancy

For security reasons, the API returns 404 rather than 403 when you attempt to access a resource that exists but belongs to another organization. This prevents information disclosure about what resources exist in other organizations.

429 Too Many Requests

You have exceeded the rate limit. Wait before making additional requests.

Example: Rate limit exceeded

# Making too many requests in a short time
for i in {1..100}; do
  curl -X POST https://api.entryguard.io/api/v1/sessions \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"durationHours": 2}'
done

Response: 429 Too Many Requests

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "path": "/api/v1/sessions"
}

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248660

Resolution

• Wait until the rate limit resets (check X-RateLimit-Reset header)
• Reduce request frequency
• Contact support to request higher rate limits

500 Internal Server Error

An unexpected error occurred on the server. These errors are logged and monitored.

Example

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later.",
  "path": "/api/v1/sessions"
}

Resolution

• Retry the request after a brief delay
• If the error persists, contact support with the timestamp and request details
• Check the status page for any ongoing incidents

Error Handling Best Practices

Retry Logic

Implement exponential backoff for transient errors (429, 500, 503):

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return await response.json();
      }

      if (response.status === 429 || response.status >= 500) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      // Non-retryable error
      const error = await response.json();
      throw new Error(error.message);

    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Token Refresh

Automatically refresh expired tokens:

async function makeAuthenticatedRequest(url, accessToken, refreshToken) {
  let response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });

  // If token expired, refresh and retry
  if (response.status === 401) {
    const refreshResponse = await fetch('https://api.entryguard.io/api/v1/auth/refresh', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refreshToken })
    });

    const { accessToken: newAccessToken } = await refreshResponse.json();

    // Retry with new token
    response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${newAccessToken}`,
        'Content-Type': 'application/json'
      }
    });
  }

  return response;
}

Validation Error Handling

Display field-level validation errors to users:

try {
  const response = await fetch('https://api.entryguard.io/api/v1/auth/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      organizationName: '',
      email: 'invalid',
      password: 'short'
    })
  });

  if (!response.ok) {
    const error = await response.json();

    if (error.validationErrors) {
      // Display field-level errors
      Object.entries(error.validationErrors).forEach(([field, message]) => {
        console.error(`${field}: ${message}`);
        // Show error next to form field
      });
    } else {
      // Display general error message
      console.error(error.message);
    }
  }
} catch (error) {
  console.error('Network error:', error);
}

Support

If you encounter persistent errors or need assistance:

• Check the API documentation
• Review the status page for known issues
• Contact support at [email protected] with:
  • Error timestamp
  • Request path and method
  • Error message and status code
  • Steps to reproduce