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)

​
200 - OK
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
{
  "links": {
    "self": "https://api.digitzs.com/merchants"
  },
  "data": {
    "type": "merchants",
    "id": "merchant-123",
    "attributes": { ... }
  }
}
​
201 - Created
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
{
  "links": {
    "self": "https://api.digitzs.com/payments"
  },
  "data": {
    "type": "payments",
    "id": "payment-456",
    "attributes": { ... }
  }
}

​
Client Error Codes (4xx)

​
400 - Bad Request
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
{
  "errors": [{
    "status": "400",
    "title": "Bad Request",
    "detail": "The amount field is required"
  }]
}
​
401 - Unauthorized
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
{
  "errors": [{
    "status": "401",
    "title": "Unauthorized",
    "detail": "An authorization header is required"
  }]
}
​
402 - Payment Required
Error
Reserved for future use. This status code is not currently used by the Digitzs API.
​
403 - Forbidden
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
{
  "errors": [{
    "status": "403",
    "title": "Forbidden",
    "detail": "The account is not authorized"
  }]
}
​
404 - Not Found
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
{
  "errors": [{
    "status": "404",
    "title": "Not Found",
    "detail": "The resource cannot be found"
  }]
}
​
408 - Request Timeout
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
{
  "errors": [{
    "status": "408",
    "title": "Request Timeout",
    "detail": "The server timed out"
  }]
}
​
409 - Conflict
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
{
  "errors": [{
    "status": "409",
    "title": "Conflict",
    "detail": "There is an editing conflict"
  }]
}
​
429 - Too Many Requests
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
{
  "errors": [{
    "status": "429",
    "title": "Too Many Requests",
    "detail": "The user has sent too many requests"
  }]
}

​
Server Error Codes (5xx)

​
500 - Internal Server Error
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
{
  "errors": [{
    "status": "500",
    "title": "Internal Server Error",
    "detail": "There was an unexpected error"
  }]
}
​
501 - Not Implemented
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
{
  "errors": [{
    "status": "501",
    "title": "Not Implemented",
    "detail": "The request method not recognized"
  }]
}
​
502 - Bad Gateway
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
{
  "errors": [{
    "status": "502",
    "title": "Bad Gateway",
    "detail": "The response is invalid"
  }]
}
​
503 - Service Unavailable
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
{
  "errors": [{
    "status": "503",
    "title": "Service Unavailable",
    "detail": "The server is currently unavailable"
  }]
}
​
504 - Gateway Timeout
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
{
  "errors": [{
    "status": "504",
    "title": "Gateway Timeout",
    "detail": "A timely response was not received"
  }]
}

​
Error Response Format

All error responses from the Digitzs API follow a consistent JSON format: 
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The amount field is required",
      "source": {
        "pointer": "/data/attributes/transaction/amount"
      }
    }
  ]
}

​
Error Object Fields

FieldTypeDescription
statusstringHTTP status code as a string
titlestringShort, human-readable summary of the error
detailstringDetailed explanation of the specific error
sourceobjectOptional pointer to the source of the error in the request
source.pointerstringJSON Pointer to the field that caused the error

​
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

const axios = require('axios');

async function makeAPIRequest(config) {
  try {
    const response = await axios(config);
    return response.data;
  } catch (error) {
    if (error.response) {
      const status = error.response.status;
      const errorData = error.response.data;

      // Handle specific error codes
      switch (status) {
        case 401:
          console.error('Authentication failed. Refreshing token...');
          // Refresh token and retry
          break;

        case 404:
          console.error('Resource not found:', errorData.errors[0].detail);
          throw new Error('Resource not found');

        case 429:
          console.error('Rate limit exceeded. Retrying after delay...');
          await delay(5000);
          return makeAPIRequest(config); // Retry

        case 500:
        case 502:
        case 503:
        case 504:
          console.error('Server error. Retrying...');
          await delay(2000);
          return makeAPIRequest(config); // Retry

        default:
          console.error('API Error:', errorData);
          throw error;
      }
    } else {
      // Network error or no response
      console.error('Network error:', error.message);
      throw error;
    }
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

​
Quick Reference Table

Status CodeMeaningAction Required
200OKRequest successful
201CreatedResource created successfully
400Bad RequestFix request parameters
401UnauthorizedRefresh authentication token
403ForbiddenCheck account permissions
404Not FoundVerify resource ID
408Request TimeoutRetry the request
409ConflictResolve resource conflict
429Too Many RequestsImplement rate limiting
500Internal Server ErrorRetry or contact support
501Not ImplementedCheck HTTP method
502Bad GatewayRetry the request
503Service UnavailableWait and retry
504Gateway TimeoutRetry the request

​
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