API Guidelines

Complete reference for API response formats, status codes, and error handling.

Status Codes

Code	Description	Error Code Constant
200	Success	OKAY
403	Unauthorized - Invalid credentials or token	UNAUTHORIZED
407	Access Denied	ACCESS_DENIED
435	Insufficient Parameters - Missing required fields	INSUFFICIENT_PARAMS
436	Validation Error - Invalid parameter format	VALIDATION
437	Not Found - Resource not found	NOT_FOUND
500	Server Fault - Internal server error	SERVER_FAULT

Error Response Format

{
  statusCode: number; // One of the status codes listed above
  data: {
  } // Empty object for error responses
  message: string; // Error message or error code constant
}

Error Code Constants

The API uses the following error code constants in the message field:

• OKAY - Request succeeded
• UNAUTHORIZED - Authentication failed or invalid credentials
• ACCESS_DENIED - User does not have permission to access the resource
• INSUFFICIENT_PARAMS - Missing required parameters
• ENTRY_NOT_FOUND - Requested resource not found
• SERVER_FAULT - Internal server error

Example Error Responses

Insufficient Parameters (435)

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: client_id, client_secret, fingerprint, user";
}

Unauthorized (403)

{
  statusCode: 403;
  data: {
  }
  message: "Invalid client credentials";
}

Validation Error (436)

{
  statusCode: 436;
  data: {
  }
  message: "1. Invalid email format in user.email, 2. Date must be in YYYY-MM-DD format in user.date_of_birth";
}

Not Found (437)

{
  statusCode: 437;
  data: {
  }
  message: "ENTRY_NOT_FOUND";
}

Server Fault (500)

{
  statusCode: 500;
  data: {
  }
  message: "SERVER_FAULT";
}

Token Format

All tokens are JWT (JSON Web Tokens) signed with a secret key. Tokens contain:

• Header: Algorithm and token type
• Payload: User information and claims
• Signature: Cryptographic signature

Security Considerations

1. HTTPS Only: Always use HTTPS in production
2. Token Storage: Store tokens securely (not in localStorage for web)
3. Client Credentials: Use client credentials for server-to-server auth