Error Handling

Semaswift uses standard HTTP status codes and provides detailed error information to help you diagnose issues.

Error Response Format

{
  "code": 400,
  "message": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ],
  "request_id": "req_abc123xyz"
}

HTTP Status Codes

Success Codes (2xx)

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

Client Error Codes (4xx)

Code	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Authentication required or failed
403 Forbidden	Insufficient permissions
404 Not Found	Resource does not exist
409 Conflict	Resource conflict (e.g., duplicate)
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded

Server Error Codes (5xx)

Code	Description
500 Internal Server Error	Unexpected server error
502 Bad Gateway	Upstream service error
503 Service Unavailable	Temporary maintenance
504 Gateway Timeout	Upstream service timeout

Error Codes Reference

Authentication Errors

Code	HTTP	Description	Resolution
AUTH_001	401	Invalid credentials	Check email/password
AUTH_002	401	Token expired	Refresh your token
AUTH_003	401	Token invalid	Re-authenticate
AUTH_004	403	Account disabled	Contact support
AUTH_005	403	MFA required	Complete MFA verification
AUTH_006	429	Too many login attempts	Wait and retry

Authorization Errors

Code	HTTP	Description	Resolution
AUTHZ_001	403	Permission denied	Request access from admin
AUTHZ_002	403	Resource not accessible	Check organization membership
AUTHZ_003	403	Action not allowed	Check role permissions

Validation Errors

Code	HTTP	Description	Resolution
VAL_001	400	Required field missing	Provide required fields
VAL_002	400	Invalid field format	Check field format
VAL_003	400	Value out of range	Check allowed values
VAL_004	400	Invalid JSON	Fix JSON syntax

Resource Errors

Code	HTTP	Description	Resolution
RES_001	404	Resource not found	Check resource ID
RES_002	409	Duplicate resource	Use existing resource
RES_003	409	Resource in use	Remove dependencies first
RES_004	410	Resource deleted	Resource no longer exists

Handling Errors

JavaScript Example

async function makeRequest(url, options) {
  const response = await fetch(url, options);

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

    switch (response.status) {
      case 401:
        // Token expired - refresh and retry
        if (error.error_code === 'AUTH_002') {
          await refreshToken();
          return makeRequest(url, options);
        }
        throw new AuthError(error.message);

      case 403:
        throw new PermissionError(error.message);

      case 404:
        throw new NotFoundError(error.message);

      case 422:
        throw new ValidationError(error.details);

      case 429:
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        return makeRequest(url, options);

      default:
        throw new APIError(error.message, error.code);
    }
  }

  return response.json();
}

Python Example

import requests

class SemaswiftAPIError(Exception):
    def __init__(self, code, message, details=None):
        self.code = code
        self.message = message
        self.details = details or []

def make_request(method, url, **kwargs):
    response = requests.request(method, url, **kwargs)

    if not response.ok:
        error = response.json()
        raise SemaswiftAPIError(
            code=error.get('error_code'),
            message=error.get('message'),
            details=error.get('details', [])
        )

    return response.json()

# Usage
try:
    user = make_request('GET', '/api/v1/users/123')
except SemaswiftAPIError as e:
    if e.code == 'AUTH_002':
        refresh_token()
        user = make_request('GET', '/api/v1/users/123')
    elif e.code == 'RES_001':
        print(f"User not found")
    else:
        raise

Request ID

Every response includes a request_id header:

X-Request-ID: req_abc123xyz

Include this ID when contacting support for faster issue resolution.

Best Practices

1. Always check status codes - Don't assume success
2. Parse error details - Use field-level errors for forms
3. Log request IDs - For debugging and support
4. Implement retry logic - For transient errors (5xx, 429)
5. Show user-friendly messages - Don't expose raw errors