​
Overview

Contazen uses conventional HTTP response codes to indicate the success or failure of an API request.
RangeMeaning
2xxSuccess - Request completed successfully
4xxClient Error - Invalid request parameters
5xxServer Error - Something went wrong on our end

​
Error Response Format

All error responses follow a consistent structure: 
{
  "success": false,
  "error": {
    "message": "Human-readable error message",
    "type": "error_type",
    "code": "error_code",
    "status": 400
  },
  "meta": {
    "version": "v1",
    "response_time": "12.5ms"
  }
}

​
Error Types

​
Handling Errors

​
Best Practices

1

Always check the response status

Don’t assume a request succeeded. Check the HTTP status code and success field.
2

Log error details

Store the full error response, especially the request_id for debugging.
3

Handle specific error types

Implement different handling for different error types.
4

Implement retry logic

For 5xx errors and rate limits, implement exponential backoff.

​
Example Error Handling

async function makeApiRequest(endpoint, options = {}) {
  try {
    const response = await fetch(`${API_BASE}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    const data = await response.json();

    if (!response.ok) {
      // Handle different error types
      switch (data.error?.type) {
        case 'authentication_error':
          throw new AuthError(data.error.message);
        
        case 'validation_error':
          throw new ValidationError(data.error.message, data.error.errors);
        
        case 'rate_limit_error':
          const retryAfter = data.error.retry_after || 60;
          throw new RateLimitError(data.error.message, retryAfter);
        
        default:
          throw new ApiError(data.error.message, data.error.code);
      }
    }

    return data;
  } catch (error) {
    // Handle network errors
    if (error instanceof TypeError) {
      throw new NetworkError('Network request failed');
    }
    throw error;
  }
}

// Usage with retry logic
async function createInvoiceWithRetry(invoiceData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await makeApiRequest('/invoices', {
        method: 'POST',
        body: JSON.stringify(invoiceData)
      });
    } catch (error) {
      if (error instanceof RateLimitError) {
        // Wait and retry
        await sleep(error.retryAfter * 1000);
        continue;
      }
      
      if (error instanceof ApiError && i < maxRetries - 1) {
        // Exponential backoff for server errors
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      
      throw error;
    }
  }
}

​
Common Error Scenarios

Invalid CUI Format

{
  "error": {
    "message": "Validation failed",
    "errors": {
      "cui": "CUI must be RO followed by 2-10 digits"
    }
  }
}
Solution: Ensure CUI starts with “RO” for Romanian companies

Duplicate Invoice Number

{
  "error": {
    "message": "Invoice number already exists",
    "code": "duplicate_invoice_number"
  }
}
Solution: Let the system auto-generate numbers

Missing Required Fields

{
  "error": {
    "message": "Validation failed",
    "errors": {
      "items": "At least one item is required",
      "client_id": "Client is required"
    }
  }
}
Solution: Check all required fields are provided

Invalid Date Format

{
  "error": {
    "message": "Invalid date format",
    "errors": {
      "date": "Date must be in YYYY-MM-DD format"
    }
  }
}
Solution: Use ISO 8601 date format

​
Getting Help

If you encounter an error you can’t resolve:
  1. Check the error message and code - They provide specific information about what went wrong
  2. Review the API documentation - Ensure you’re using the correct parameters
  3. Include the request ID - Found in error responses for server errors
  4. Contact support - Email contact@contazen.ro with details