Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.contazen.ro/llms.txt

Use this file to discover all available pages before exploring further.

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

Type: authentication_errorThese errors occur when there’s a problem with your API key.
CodeStatusDescription
missing_api_key401No Authorization header provided
invalid_api_key401API key doesn’t exist or is invalid
expired_api_key401API key has expired
ip_restricted401Request from unauthorized IP
insufficient_permissions403API key lacks required permissions
Example:
{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "status": 401
  }
}
Type: validation_errorThese errors occur when request parameters fail validation.
CodeStatusDescription
invalid_request400General validation failure
missing_required_field400Required field not provided
invalid_field_value400Field value doesn’t meet requirements
invalid_format400Data format is incorrect
Example with field-specific errors:
{
  "success": false,
  "error": {
    "message": "Validation failed",
    "type": "validation_error",
    "code": "invalid_request",
    "status": 400,
    "errors": {
      "client_data.cui": "Invalid CUI format",
      "items.0.price": "Price must be greater than 0",
      "email": "Invalid email address"
    }
  }
}
Type: rate_limit_errorReturned when you exceed the allowed number of requests.
CodeStatusDescription
rate_limit_exceeded429Too many requests
Example:
{
  "success": false,
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retry_after": 45,
    "status": 429
  }
}
Check the response headers for rate limit information:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Reset time (Unix timestamp)
Type: resource_errorThese errors relate to specific resources.
CodeStatusDescription
resource_not_found404Requested resource doesn’t exist
resource_already_exists409Resource with same identifier exists
resource_locked423Resource is locked for editing
Example:
{
  "success": false,
  "error": {
    "message": "Client not found",
    "type": "resource_error",
    "code": "resource_not_found",
    "status": 404
  }
}
Type: api_errorThese indicate problems on our servers.
CodeStatusDescription
internal_server_error500Unexpected server error
service_unavailable503Service temporarily unavailable
Example:
{
  "success": false,
  "error": {
    "message": "An unexpected error occurred",
    "type": "api_error",
    "code": "internal_server_error",
    "status": 500,
    "request_id": "req_1a2b3c4d5e"
  }
}

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

e-Factura Not Configured

{
  "error": {
    "message": "e-Factura OAuth not configured",
    "code": "efactura_oauth_not_configured",
    "type": "invalid_request_error"
  }
}
Solution: Complete OAuth setup in settings

Invoice Already Sent to SPV

{
  "error": {
    "message": "Invoice already sent to SPV",
    "code": "already_sent_to_spv",
    "current_status": "submitted"
  }
}
Solution: Check invoice status before sending

Cannot Delete Used Product

{
  "error": {
    "message": "Cannot delete product with associated invoices",
    "code": "product_has_invoices",
    "invoice_count": 5
  }
}
Solution: Products used in invoices cannot be deleted

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