Skip to main content

Error Handling

Learn about standard error formats and error codes across all Debitura APIs.

Overview​

All Debitura APIs use consistent error formats to help you quickly identify and resolve issues. This guide covers error response structures, common error codes, and best practices for handling errors in your integration.

Error Response Format​

When an error occurs, the API returns a JSON response with the following structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context about the error"
    }
  }
}

Error Response Fields​

  • code - Machine-readable error code (see error codes below)
  • message - Human-readable description of what went wrong
  • details - Optional object containing additional context about the error

HTTP Status Codes​

Debitura APIs use standard HTTP status codes to indicate the success or failure of requests:

2xx Success​

  • 200 OK - Request succeeded
  • 201 Created - Resource successfully created
  • 204 No Content - Request succeeded with no response body

4xx Client Errors​

  • 400 Bad Request - Invalid request parameters or malformed JSON
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 403 Forbidden - Valid credentials but insufficient permissions
  • 404 Not Found - Requested resource doesn't exist
  • 409 Conflict - Request conflicts with current state (e.g., duplicate resource)
  • 422 Unprocessable Entity - Valid syntax but semantically incorrect
  • 429 Too Many Requests - Rate limit exceeded

5xx Server Errors​

  • 500 Internal Server Error - Unexpected server error
  • 503 Service Unavailable - Service temporarily unavailable (maintenance or overload)

Common Error Codes​

Authentication Errors​

  • invalid_api_key - The provided API key is invalid or expired
  • missing_authentication - No authentication credentials provided
  • invalid_token - Bearer token is invalid or expired

Authorization Errors​

  • insufficient_permissions - Authenticated but lacking required permissions
  • resource_not_accessible - Cannot access the requested resource

Validation Errors​

  • validation_error - One or more fields failed validation
  • invalid_format - Field value doesn't match expected format
  • missing_required_field - Required field is missing
  • invalid_value - Field value is outside acceptable range

Resource Errors​

  • resource_not_found - Requested resource doesn't exist
  • duplicate_resource - Resource with same identifier already exists
  • resource_conflict - Operation conflicts with resource state

Rate Limiting​

  • rate_limit_exceeded - Too many requests in given time period

Error Handling Best Practices​

Retry Logic​

For 5xx server errors and 429 rate limit errors, implement exponential backoff retry logic:

// Example retry logic will be documented here

Validation Errors​

For validation_error responses, check the details object for field-specific error messages:

// Example validation error handling will be documented here

Logging and Monitoring​

Log all error responses for debugging and monitoring purposes. Include request IDs when available.

Getting Help​

If you encounter errors you can't resolve:

  • Review the specific API reference for your endpoint
  • Contact support with the error details and request ID
  • Visit the Support Center