agmission/Development/server/docs/SATLOC_API_ACTUAL_BEHAVIOR.md

SatLoc API Actual Behavior - Test Results

Test Date

October 3, 2025

Test Methodology

Created test scripts to call actual SatLoc API endpoints with various invalid credential scenarios to discover real error responses (instead of making assumptions).

---

Authentication Endpoint

Endpoint: GET /api/Satloc/AuthenticateAPIUser?userLogin={username}&password={password}

Success Response

HTTP Status: 200 OK

Response Body:

{
  "userId": "a2991888-5c7f-4101-8e0d-0a390c26720c",
  "companyId": "36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff",
  "email": "vendor@myk.com"
}

Characteristics:

• ✅ Status code: 200
• ✅ Response is JSON object
• ✅ Contains userId, companyId, email fields
• ✅ Has Content-Type header

---

Authentication Failure Response

HTTP Status: 400 Bad Request

Status Text: "Invalid Username or Password provide."

Response Body: "" (empty string, not JSON!)

Response Headers:

• ❌ NO Content-Type header
• Response body is empty string

Test Scenarios That Produce This:

1. ✅ Wrong username and password
2. ✅ Wrong password only
3. ✅ Empty password
4. ✅ SQL injection attempts
5. ✅ Special characters in password

Characteristics:

• ❌ Status code: 400 (NOT 401 or 403!)
• ❌ Response is empty string "" (NOT JSON with ErrorMessage field!)
• ❌ No Content-Type header
• ✅ Error info in statusText field

---

Server Error Response

HTTP Status: 500 Internal Server Error

Test Scenario: Empty username parameter

Response Body:

{
  "message": "An error has occurred."
}

Characteristics:

• ❌ Status code: 500
• ✅ Response is JSON object
• ✅ Has message field
• ✅ Has Content-Type: application/json

---

Key Findings

❌ WRONG Assumptions (What We Thought)

1. Authentication failures return 401/403 → ❌ FALSE, returns 400
2. Error responses have ErrorMessage field → ❌ FALSE, response.data is empty string
3. Error responses are JSON objects → ❌ FALSE, they're empty strings
4. Can check response.data.ErrorMessage → ❌ FALSE, this field doesn't exist

✅ CORRECT Behavior (What Actually Happens)

1. Authentication failures return HTTP 400 → ✅ TRUE
2. Error info is in statusText → ✅ TRUE: "Invalid Username or Password provide."
3. Error response body is empty string → ✅ TRUE: ""
4. Success has status 200 with JSON object → ✅ TRUE
5. Success response has userId and companyId → ✅ TRUE

---

Code Implications

Before (Wrong Assumptions)

// ❌ This doesn't work!
if (!response.data || response.data.ErrorMessage) {
  // SatLoc doesn't return ErrorMessage field!
}

// ❌ This doesn't work!
if (status === 401 || status === 403) {
  // SatLoc returns 400, not 401/403!
}

After (Based on Real API)

// ✅ Check status code (400 for auth failures)
if (response.status !== 200 || !response.data || typeof response.data !== 'object') {
  // Use statusText for error message
  const errorMessage = response.statusText || `Authentication failed`;
  throw new AppAuthError(Errors.WRONG_CREDENTIAL, errorMessage);
}

// ✅ Verify required fields exist
if (!response.data.userId || !response.data.companyId) {
  throw new AppAuthError(Errors.WRONG_CREDENTIAL, 'Missing userId or companyId');
}

---

Error Detection in isAuthError()

Before (Guessing)

// ❌ Won't work - SatLoc doesn't return these codes
if (status === 401 || status === 403) {
  return true;
}

After (Tested)

// ✅ Check actual status code
if (status === 400) {
  const statusText = (error.response?.statusText || '').toLowerCase();
  // ✅ Verify it's authentication-related via statusText
  if (statusText.includes('invalid username') || 
      statusText.includes('invalid password') ||
      statusText.includes('username or password')) {
    return true;
  }
}

// ✅ Check for AppAuthError thrown by our code
if (error.name === 'AppAuthError') {
  return true;
}

---

Response Format Summary

Scenario	Status	Response Type	Has Content-Type	Key Fields
Success	200	JSON object	✅ Yes	userId, companyId, email
Auth Failure	400	Empty string	❌ No	(none - use statusText)
Server Error	500	JSON object	✅ Yes	message

---

Testing Recommendations

Unit Tests Should Verify:

1. Success case:

   • Status 200
   • Response is object with userId, companyId, email

2. Auth failure case:

   • Status 400
   • statusText contains "Invalid Username or Password"
   • Response body is empty string
   • Code throws AppAuthError

3. Server error case:

   • Status 500
   • Request throws exception
   • Error includes response data

Integration Tests Should:

1. Test with valid credentials → Verify success response format
2. Test with invalid credentials → Verify 400 status + statusText
3. Test retry logic → Verify cache clearing on auth failures
4. Test worker behavior → Verify authentication errors are retryable

---

Conclusion

Never assume API behavior based on "common patterns" or "standard practices".

Testing revealed that SatLoc API:

• Uses HTTP 400 for authentication failures (not 401/403)
• Returns empty string for errors (not JSON with ErrorMessage)
• Puts error details in statusText (not response body)

This is why actual testing beats assumptions every time. The updated code now correctly handles real SatLoc API behavior.

---

Test Scripts Created

1. test_satloc_errors_simple.js - Tests various auth failure scenarios
2. test_satloc_error_responses.js - More comprehensive testing with database integration

Run these to verify API behavior changes in the future.