Skip to main content

Overview

The Digitzs API uses standard HTTP status codes to indicate the success or failure of API requests. When an error occurs, the API returns a status code that helps you understand what went wrong and how to fix it.
Status codes follow the Internet Engineering Task Force (IETF) Request for Comments (RFCs) standards.

Status Code Categories

HTTP status codes are organized into five categories based on the first digit:

1xx - Informational

The request was received, continuing process

2xx - Successful

The request was successfully received, understood, and accepted

3xx - Redirection

Further action is necessary to complete the request

4xx - Client Error

The request contains bad syntax or cannot be fulfilled

5xx - Server Error

The server failed to fulfill an apparently valid request

HTTP Status Codes

Success Codes (2xx)

Success
The request was successful and the server returned the requested data.When you’ll see it:
  • Successfully retrieving merchant data
  • Successfully retrieving payment information
  • Successfully listing resources
Success
The request was successful and a new resource was created.When you’ll see it:
  • Creating a new merchant account
  • Processing a new payment
  • Generating authentication tokens

Client Error Codes (4xx)

Error
The server cannot process the request due to invalid syntax or missing required parameters.Common causes:
  • Missing required fields in request body
  • Invalid data format (e.g., non-numeric amount)
  • Malformed JSON
  • Invalid parameter values
How to fix:
  • Verify all required fields are included
  • Check data types match the API specification
  • Validate JSON syntax
  • Review the error message for specific field issues
Error
Authentication is required or has failed. The request lacks valid authentication credentials.Common causes:
  • Missing Authorization header
  • Expired app token (tokens expire after 1 hour)
  • Invalid or malformed token
  • Missing x-api-key header
How to fix:
  • Generate a new app token using /auth/token
  • Ensure Authorization header format is Bearer {token} with capital “B”
  • Verify your API key is correct
  • Include all required authentication headers
Error
Reserved for future use. This status code is not currently used by the Digitzs API.
Error
The server understood the request but refuses to authorize it.Common causes:
  • Account is not authorized to access the resource
  • API key has been revoked or suspended
  • Insufficient permissions for the requested operation
  • Attempting to access another merchant’s data
How to fix:
  • Contact Digitzs support to verify account status
  • Check that you’re accessing resources you own
  • Verify your account permissions
Error
The requested resource could not be found on the server.Common causes:
  • Invalid resource ID (merchant ID, payment ID, etc.)
  • Resource has been deleted
  • Incorrect API endpoint URL
  • Typo in the request path
How to fix:
  • Verify the resource ID exists and is correct
  • Check the endpoint URL for typos
  • Ensure you’re using the correct HTTP method
  • Confirm the resource hasn’t been deleted
Error
The server timed out waiting for the request.Common causes:
  • Slow network connection
  • Large request payload
  • Server processing delays
How to fix:
  • Retry the request
  • Check your network connection
  • Reduce request payload size if possible
  • Implement retry logic with exponential backoff
Error
The request conflicts with the current state of the server.Common causes:
  • Attempting to create a duplicate resource
  • Race condition with concurrent requests
  • Editing conflict with another user’s changes
How to fix:
  • Check if the resource already exists
  • Implement optimistic locking if handling concurrent updates
  • Retry the request with updated data
Error
The user has sent too many requests in a given amount of time (rate limiting).Common causes:
  • Exceeding API rate limits
  • Making too many requests in a short time period
  • Not implementing proper request throttling
How to fix:
  • Implement exponential backoff
  • Add delays between requests
  • Cache responses when possible
  • Contact support if you need higher rate limits

Server Error Codes (5xx)

Error
The server encountered an unexpected condition that prevented it from fulfilling the request.Common causes:
  • Unexpected server-side error
  • Database connection issues
  • Unhandled exception in server code
How to fix:
  • Retry the request after a short delay
  • If the error persists, contact Digitzs support
  • Check Digitzs status page for known issues
Error
The server does not recognize the request method or lacks the ability to fulfill it.Common causes:
  • Using an unsupported HTTP method
  • Calling an endpoint that doesn’t support the method
  • Feature not yet implemented
How to fix:
  • Verify you’re using the correct HTTP method (GET, POST, PUT, DELETE)
  • Check the API documentation for supported methods
  • Ensure the endpoint supports the requested operation
Error
The server received an invalid response from an upstream server.Common causes:
  • Payment processor connection issues
  • Third-party service unavailable
  • Network problems between servers
How to fix:
  • Retry the request
  • Wait a few moments and try again
  • If the error persists, contact Digitzs support
Error
The server is currently unable to handle the request due to temporary overload or maintenance.Common causes:
  • Scheduled maintenance
  • Server overload
  • Temporary service disruption
How to fix:
  • Wait and retry the request
  • Check Digitzs status page
  • Implement retry logic with exponential backoff
Error
The server did not receive a timely response from an upstream server.Common causes:
  • Payment processor timeout
  • Long-running operation exceeded timeout
  • Network latency issues
How to fix:
  • Retry the request
  • Check payment status before retrying payment operations
  • Contact support if timeouts persist

Error Response Format

All error responses from the Digitzs API follow a consistent JSON format:

Error Object Fields

Handling Errors

Best Practices

Log All Errors

Log error responses with full details for debugging and monitoring

Implement Retry Logic

Retry transient errors (5xx, 408, 429) with exponential backoff

Parse Error Details

Read the error detail field for specific information about what went wrong

Handle Gracefully

Display user-friendly error messages instead of raw error responses

Example Error Handling

Quick Reference Table

Preventing Common Errors

  • Implement automatic token refresh before expiration
  • Cache tokens and track their expiration time
  • Use the correct Authorization header format: Bearer {token}
  • Include all required headers: Authorization, x-api-key, and appId
  • Validate all input data before sending requests
  • Use the correct data types (strings, numbers, etc.)
  • Include all required fields
  • Test with the API documentation examples
  • Implement request throttling in your application
  • Cache responses when possible
  • Use batch operations instead of individual requests
  • Monitor your request rate
  • Implement exponential backoff for retries
  • Set reasonable timeout values
  • Log errors for monitoring
  • Have a fallback strategy for critical operations

Need Help?

Contact Support

If you encounter persistent errors or need assistance troubleshooting, our support team is here to help.

Additional Resources

Authentication Guide

Learn how to properly authenticate your requests

API Reference

Explore detailed endpoint documentation