Error Handling

Error Response Format

The GetBill API uses conventional HTTP response codes to indicate the success or failure of an API request. All error responses follow a consistent JSON format:

{
  "error": true,
  "message": "A human-readable error message",
  "code": 400,
  "details": {
    "field_name": ["Specific field error message"]
  }
}

boolean

Always true for error responses

string

A human-readable description of the error

integer

The HTTP status code

object

Additional error details, often including field-specific validation errors

HTTP Status Codes

2xx Success

200 OK: The request was successful
201 Created: A new resource was successfully created
202 Accepted: Asynchronous processing was queued; poll the URL in Location

4xx Client Errors

400 Bad Request: The request was invalid or malformed
401 Unauthorized: Authentication credentials are missing or invalid
403 Forbidden: The authenticated user doesn’t have permission to access the resource
404 Not Found: The requested resource doesn’t exist
409 Conflict: The request conflicts with current resource or idempotency state
413 Content Too Large: The request body exceeds the endpoint limit
422 Unprocessable Entity: The request is valid but contains semantic errors
429 Too Many Requests: Rate limit exceeded

5xx Server Errors

500 Internal Server Error: An unexpected error occurred on the server
502 Bad Gateway: The server received an invalid response from an upstream server
503 Service Unavailable: The service is temporarily unavailable
504 Gateway Timeout: The server didn’t receive a response from an upstream server in time

Common Error Scenarios

Authentication Errors

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}

Solution: Ensure you’re including a valid access token in the Authorization header.

Authorization Errors

{
  "error": true,
  "message": "Required scope \"debts:write\" not found in token",
  "code": 403
}

Solution: Request the appropriate scopes when obtaining your access token.

Validation Errors

{
  "error": true,
  "message": "Validation failed",
  "code": 400,
  "details": {
    "firstname": ["First name is required"],
    "amount": ["Valid amount is required"],
    "phone": ["Phone number is required"]
  }
}

Solution: Check the details object for field-specific errors and correct your request data.

Resource Not Found

{
  "error": true,
  "message": "Debt not found or invalid ID",
  "code": 404
}

Solution: Verify the resource ID exists and you have permission to access it.

Rate Limiting

{
  "error": true,
  "message": "Rate limit exceeded. Please try again later.",
  "code": 429,
  "details": {
    "retry_after": 60,
    "limit": 100,
    "reset_time": "2024-01-15T10:30:00Z"
  }
}

Solution: Implement exponential backoff and respect the retry_after value.

Campaign snapshot errors

Campaign endpoints retain the numeric HTTP status in code and put the stable machine-readable value in details.reason. Validation may also identify a one-based details.row and details.field.

{
  "error": true,
  "message": "Duplicate effective identity.",
  "code": 400,
  "details": {
    "reason": "invalid_snapshot_row",
    "row": 42,
    "field": "internal_id"
  }
}

HTTP/status	Reason	Meaning
400	`invalid_request`	Malformed JSON, unknown field, or invalid primitive value
400	`invalid_reference`	Campaign or snapshot reference does not match the required format
400	`invalid_status`	Campaign list status is not `active`, `paused`, or `completed`
400 or `failed`	`invalid_snapshot_row`	Row validation or debt identity conflict; `row` and `field` may be present
400	`row_count_limit_exceeded`	Request, chunk, total, or declared count exceeds its limit
403	`company_not_authorized`	The OAuth client is not associated with a company
403	`campaign_api_not_enabled`	Campaign import/API access is disabled for the OAuth company
404	`campaign_not_found`	Campaign is missing or belongs to another company
404	`snapshot_not_found`	Snapshot is missing or belongs to another company
409	`campaign_configuration_required`	Campaign setup is incomplete or changed; complete the setup in GetBill
409	`campaign_not_active`	Campaign is paused or completed
409	`campaign_mode_not_supported`	Campaign cannot accept snapshot synchronization; ask a GetBill administrator to configure it
409	`campaign_reference_conflict`	Campaign is not valid for generic API snapshots
409	`snapshot_in_progress`	Another non-terminal snapshot blocks this campaign
409	`snapshot_reference_conflict`	The reference was retried with different data for the same delivery method
409	`snapshot_delivery_mode_conflict`	The reference cannot switch between one-request and staged delivery
409	`snapshot_not_uploading`	Chunks or cancellation are no longer accepted
409	`snapshot_incomplete`	Received and expected row counts differ
409	`chunk_out_of_order`	Chunk index is not the next expected index
409	`chunk_content_conflict`	Retried chunk bytes differ from the accepted body
`failed`	`ambiguous_debt_identity`	Existing debt records cannot be matched unambiguously
409	`snapshot_processing_error`	Core may be applied; GetBill operator recovery is required
413	`payload_too_large`	Request body exceeds 10 MiB
500	`snapshot_processing_failed`	Safe generic processing failure; retry or contact support

The terminal status API may report safe failure reasons such as client_aborted_upload, stale_snapshot_upload, snapshot_retries_exhausted, or a validation reason. It never returns raw rows, SQL, paths, implementation details, or exception text.

When status is processing_error, inspect core_applied. Do not create a replacement snapshot while the campaign is blocked; contact GetBill support for idempotent operator recovery.

Error Handling Best Practices

1. Implement Proper Error Handling

async function createDebt(debtData) {
  try {
    const response = await fetch('/external-api/v1/debts', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(debtData)
    });

    if (!response.ok) {
      const error = await response.json();
      
      if (response.status === 401) {
        // Handle authentication error
        await requestNewAccessToken();
        return createDebt(debtData); // Retry
      }
      
      if (response.status === 400 && error.details) {
        // Handle validation errors
        handleValidationErrors(error.details);
        return;
      }
      
      throw new Error(error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to create debt:', error);
    throw error;
  }
}

2. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || 1;
        await sleep(retryAfter * 1000);
        retries++;
        continue;
      }
      
      if (response.status >= 500) {
        // Server error - exponential backoff
        await sleep(Math.pow(2, retries) * 1000);
        retries++;
        continue;
      }
      
      return response;
    } catch (error) {
      if (retries === maxRetries - 1) throw error;
      await sleep(Math.pow(2, retries) * 1000);
      retries++;
    }
  }
}

3. Log Errors for Debugging

function logApiError(endpoint, error, requestData = null) {
  console.error('API Error:', {
    endpoint,
    status: error.code,
    message: error.message,
    details: error.details,
    requestData,
    timestamp: new Date().toISOString()
  });
}

4. Handle Specific Error Types

Network Errors
Timeout Errors
Token Expiry

catch (error) {
  if (error instanceof TypeError && error.message.includes('fetch')) {
    // Network connectivity issue
    showNetworkErrorMessage();
    return;
  }
  throw error;
}

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);

try {
  const response = await fetch(url, {
    ...options,
    signal: controller.signal
  });
  clearTimeout(timeoutId);
  return response;
} catch (error) {
  if (error.name === 'AbortError') {
    throw new Error('Request timeout');
  }
  throw error;
}

async function makeAuthenticatedRequest(url, options) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${getAccessToken()}`
    }
  });

  if (response.status === 401) {
    // Token expired, request a new one and retry
    await requestNewAccessToken();
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${getAccessToken()}`
      }
    });
  }

  return response;
}

Debugging Tips

1. Check Response Headers

Important headers to examine:

X-RateLimit-Remaining: Number of requests remaining in the current window
X-RateLimit-Reset: When the rate limit window resets
Retry-After: How long to wait before retrying (for 429 responses)

2. Validate Request Format

Common issues:

Missing or incorrect Content-Type header
Malformed JSON in request body
Invalid field values or types
Missing required fields

3. Use API Testing Tools

Test your requests using tools like:

Postman
curl
Insomnia
HTTPie

4. Enable Debug Logging

Include request/response logging in your application to track API interactions and identify patterns in errors.

Support

If you encounter persistent errors or need help with error handling:

Check our Status Page for ongoing incidents
Review the specific endpoint documentation
Contact support at contact@getbill.io with:
- The specific error message
- Your request details (without sensitive data)
- Steps to reproduce the issue

Get started

Guides

SFTP integration

Company API

Creditors API

Debtors API

Debts API

Timelines API

Campaigns API

Settings API

Invoice documents API

Followups API

Todos API

Status API

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors

Authorization Errors

Validation Errors

Resource Not Found

Rate Limiting

Campaign snapshot errors

Error Handling Best Practices

1. Implement Proper Error Handling

2. Implement Retry Logic

3. Log Errors for Debugging

4. Handle Specific Error Types

Debugging Tips

1. Check Response Headers

2. Validate Request Format

3. Use API Testing Tools

4. Enable Debug Logging

Support

​Error Response Format

​HTTP Status Codes

​Common Error Scenarios

​Authentication Errors

​Authorization Errors

​Validation Errors

​Resource Not Found

​Rate Limiting

​Campaign snapshot errors

​Error Handling Best Practices

​1. Implement Proper Error Handling

​2. Implement Retry Logic

​3. Log Errors for Debugging

​4. Handle Specific Error Types

​Debugging Tips

​1. Check Response Headers

​2. Validate Request Format

​3. Use API Testing Tools

​4. Enable Debug Logging

​Support

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors

Authorization Errors

Validation Errors

Resource Not Found

Rate Limiting

Campaign snapshot errors

Error Handling Best Practices

1. Implement Proper Error Handling

2. Implement Retry Logic

3. Log Errors for Debugging

4. Handle Specific Error Types

Debugging Tips

1. Check Response Headers

2. Validate Request Format

3. Use API Testing Tools

4. Enable Debug Logging

Support