Response Codes

Response Format

All API responses follow a consistent format:

{
  "version": null,
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    // Response data
  }
}

HTTP Status Codes

Success Codes (2xx)

Code	Description	Usage
200	OK	Request succeeded
201	Created	Resource successfully created
204	No Content	Request succeeded with no response body

Client Error Codes (4xx)

Code	Description	Common Causes	Resolution
400	Bad Request	Invalid input	Check request format and parameters
401	Unauthorized	Invalid/missing token	Refresh authentication token
403	Forbidden	Insufficient permissions	Check access rights
404	Not Found	Resource doesn't exist	Verify resource ID
409	Conflict	Resource conflict	Check existing resources
429	Too Many Requests	Rate limit exceeded	Implement backoff strategy

Server Error Codes (5xx)

Code	Description	Action
500	Internal Server Error	Contact support
502	Bad Gateway	Retry request
503	Service Unavailable	Check service status
504	Gateway Timeout	Retry with backoff

Business Error Codes

Authentication Errors (AUTH)

Code	Message	Cause	Resolution
AUTH001	Invalid credentials	Wrong appId/appSecret	Check credentials
AUTH002	Token expired	JWT token expired	Request new token
AUTH003	Invalid token format	Malformed JWT	Check token format
AUTH004	Missing token	No Authorization header	Include token

Validation Errors (VAL)

Code	Message	Cause	Resolution
VAL001	Missing required field	Required field not provided	Include field
VAL002	Invalid field format	Wrong data format	Check format
VAL003	Invalid field length	Field too long/short	Adjust length
VAL004	Invalid enum value	Value not in allowed set	Check valid values

Business Logic Errors (BUS)

Code	Message	Cause	Resolution
BUS001	Invalid state transition	Invalid workflow step	Check workflow
BUS002	Duplicate entity	Entity already exists	Check existing
BUS003	Entity not found	Invalid ID	Verify ID
BUS004	Operation not allowed	Business rule violation	Check rules

Document Errors (DOC)

Code	Message	Cause	Resolution
DOC001	Invalid document type	Unsupported format	Check formats
DOC002	Document expired	Document out of date	Provide current
DOC003	Poor image quality	Low resolution/blur	Improve quality
DOC004	Missing document	Required doc not found	Upload document

Error Response Examples

Validation Error

{
  "version": null,
  "statusCode": 400,
  "messages": [
    "VAL001: Required field 'email' is missing"
  ],
  "result": null
}

Authentication Error

{
  "version": null,
  "statusCode": 401,
  "messages": [
    "AUTH002: Token has expired"
  ],
  "result": null
}

Business Logic Error

{
  "version": null,
  "statusCode": 409,
  "messages": [
    "BUS002: Customer with email already exists"
  ],
  "result": null
}

Error Handling Best Practices

1. Check Status Code First

if (response.statusCode >= 400) {
  handleError(response);
}

2. Parse Error Messages

function parseErrorCode(message: string): string {
  const match = message.match(/^([A-Z]+\d+):/);
  return match ? match[1] : 'UNKNOWN';
}

3. Implement Retry Logic

async function retryRequest(fn: Function, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryableError(error) || i === maxRetries - 1) {
        throw error;
      }
      await delay(Math.pow(2, i) * 1000);
    }
  }
}

4. Handle Rate Limits

function handleRateLimit(response) {
  if (response.statusCode === 429) {
    const retryAfter = response.headers['retry-after'];
    return new Promise(resolve => {
      setTimeout(resolve, (parseInt(retryAfter) || 60) * 1000);
    });
  }
}