Freehand for Procure

Created by Carrie Sobers, Modified on Mon, 2 Feb at 3:41 PM by Carrie Sobers

1. Authentication & Authorization Failures

Symptom: API requests return 401 Unauthorized or 403 Forbidden errors for shipper or vendor endpoints.

Diagnostic Steps:

1. Check JWT token expiration in request headers

2. Verify token format: Authorization: Bearer <token> or cl-platform-token header

3. Confirm endpoint prefix matches user type ( /fns/api for shipper, /fnv/api for vendor)

4. Review auth proxy logs for token validation failures

5. Check user status in Users table (should be ACTIVE )

6. Verify role assignments and permissions for sourcing event operations

Logs to Check:

Procure API service logs: procure-api-service.log

Look for: Token expired , Invalid token , Permission denied , Unauthorized access

Auth proxy logs: Authentication failed , User not found

Common Causes:

Expired JWT tokens (default expiration: 24 hours)

Token not included in request headers

User status is PENDING or INACTIVE

Missing permissions: view_quote_configuration , edit_quote_configuration

Vendor trying to access shipper endpoints or vice versa

Internal token misconfiguration for service-to-service calls

Resolution:

Refresh token via /cm/api/auth/refresh endpoint

Verify token in request headers (check Network tab in browser DevTools)

Update user status to ACTIVE if pending

Assign appropriate roles with sourcing event permissions

Verify endpoint prefix matches user context (shipper vs vendor)

Check internal token configuration in service settings

Verification:

Retry API request with valid token

Check bootstrap API response for user permissions

Verify token format in browser DevTools Network tab

Group 20, Grouped object

2. Database Connection Failures:

Symptom: Services fail to start or API requests return 500 errors with database connection messages.

Diagnostic Steps:

1. Verify PostgreSQL services are running (metadata and transactions databases)

2. Check database connection strings in environment configuration

3. Test database connectivity: psql -h <host> -U <user> -d <database>

4. Review connection pool settings (max connections, timeout)

5. Check database server logs for connection errors

6. Verify network connectivity between service and databases

Logs to Check:

Service startup logs: Error: connect ECONNREFUSED , Connection timeout Sequelize logs: Unable to connect to the database , Connection pool exhausted

Database server logs: too many connections , authentication failed

Common Causes:

Incorrect connection string (host, port, database name, credentials)

Database server is down or unreachable

Connection pool exhausted (too many open connections)

Network firewall blocking database port (default: 5432)

Database credentials expired or incorrect

Separate metadata and transactions database connection issues

Resolution:

Verify DATABASE_URL or individual connection parameters in config Check both metadata and transactions database connections

Restart database service if down

Increase connection pool size in Sequelize configuration Check firewall rules for database port access

Update database credentials if expired Review and close idle connections

Verification:

Service starts without connection errors Health check endpoint returns 200 OK

Database queries execute successfully on both databases