Error Handling

Error Response Structure

All API errors follow a consistent JSON structure with detailed information to help you debug issues. Here is a sample error response:

{
    "code": "4300",
    "httpMethod": "PATCH", 
    "message": "Insufficient permissions to access resource",
    "path": "/onboarding/api/v1/users/all",
    "requestId": "46a7ad4b-c315-441c-ad2c-473f4075e1b5",
    "resourcePath": "/onboarding/api/v1/{proxy+}"
}

Response Fields

Field Definitions

Field	Type	Description	Example
`code`	`string`	🏷️ Internal error code for categorization	`"4300"`, `"4030"`
`httpMethod`	`string`	🌐 HTTP method used in the request	`"GET"`, `"POST"`, `"PATCH"`
`message`	`string`	💬 Human-readable error description	`"Missing authentication token"`
`path`	`string`	🛣️ Exact API endpoint path that was called	`"/onboarding/api/v1/users/all"`
`requestId`	`string`	🔍 Unique identifier for this request (UUID)	`"46a7ad4b-c315-441c-ad2c-473f4075e1b5"`
`resourcePath`	`string`	⚙️ AWS API Gateway resource path pattern	`"/onboarding/api/v1/{proxy+}"`

Pro Tip: The requestId is your golden ticket for support - it’s like a fingerprint for your specific API call!

Always include the requestId when contacting support - it helps us quickly locate your specific request in our logs.

The code field is our internal error classification system. Use this along with the HTTP status code to programmatically handle different error scenarios.

Quick Reference

Most Common

Missing API Key (4030)Add X-API-Key header to your request

Format Issue

Invalid Format (4100)API key must be exactly 32 alphanumeric characters

Not Found

API Key Not Found (4101)Double-check your API key is correct

Permissions

Insufficient Permissions (4300)Contact support for permission updates

Complete Error Reference

Authentication Errors

[4030] - Missing API Key

Response Field	Details
HTTP Status	`403 Forbidden`
Message	Missing authentication token
Root Cause	No `X-API-Key` header provided in the request
Impact	🔴 High - Blocks all API access
Fix Time	⚡ < 1 minute

Add the X-API-Key header with your API key to all requests.

curl -H "X-API-Key: <api-key>" \
     -H "Content-Type: application/json" \
     https://api.carbnconnect.com/onboarding/api/v1/users/all

const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/users/all', {
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': '<api-key>'
  }
});

import requests

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': '<api-key>'
}

response = requests.get(
    'https://api.carbnconnect.com/onboarding/api/v1/users/all',
    headers=headers
)

[4100] - Invalid API Key Format

Response Field	Details
HTTP Status	`403 Forbidden`
Message	Invalid API key format
Root Cause	API key is not exactly 32 alphanumeric characters
Impact	🔴 High - Authentication fails
Fix Time	⚡ < 30 seconds

Verify API Key format requirements - API keys are case-sensitive and must be exactly 32 characters long (A-Z, a-z, 0-9)

[4101] - API Key Not Found

Response Field	Details
HTTP Status	`401 Unauthorized`
Message	API key not found
Root Cause	API key doesn’t exist in our system
Impact	🔴 High - Complete access denial
Fix Time	⏱️ 2-3 minutes

Verify your API key is correct or generate a new API key from the dashboard.

[4102] - API Key Expired

Response Field	Details
HTTP Status	`401 Unauthorized`
Message	API key has expired
Root Cause	API key has passed its expiration date
Impact	🔴 High - All requests blocked
Fix Time	⏱️ 2-3 minutes

Generate a new API key from your dashboard.

Pro Tip: Set up API key rotation reminders to avoid service interruptions

[4103] - API Key Inactive

Response Field	Details
HTTP Status	`401 Unauthorized`
Message	API key is inactive
Root Cause	API key has been suspended or deactivated
Impact	🔴 High - Account-level issue
Fix Time	⏰ 1-24 hours (support dependent)

Account Issue: This usually indicates a billing or compliance concern. Contact support immediately.

Authorization Errors

[4300] - Insufficient Permissions

Response Field	Details
HTTP Status	`403 Forbidden`
Message	Insufficient permissions to access resource
Root Cause	Your API key lacks the required permissions for this endpoint
Impact	🟡 Medium - Specific endpoints blocked
Fix Time	⏰ 2-24 hours (support dependent)

Permission Levels: Different endpoints require different permission levels. Check the specific endpoint documentation for required permissions.

Common Cause: This often happens when using a read-only API key for write operations (POST, PATCH, DELETE)

HTTP Status Code Reference

Success Codes (2xx)

Status Code	Status Name	Description	Action Required
`200`	OK	Your request has completed successfully	No action required
`201`	Created	Resource created successfully	No action required

2xx responses indicate successful requests. Your API call worked as expected and you can proceed with the response data.

Client Error Codes (4xx)

Status Code	Status Name	Description	Action Required
`400`	Bad Request	Request format is invalid or malformed	Fix request syntax
`401`	Unauthorized	Authentication failed or missing credentials	Check API key
`403`	Forbidden	Access forbidden due to permissions	Check permissions
`404`	Not Found	Resource doesn’t exist or not found	Verify resource ID
`429`	Rate Limited	Too many requests sent recently	Wait and retry

4xx errors mean there’s an issue with your request. Double-check your API key, request format, and permissions.

Server Error Codes (5xx)

Status Code	Status Name	Description	Action Required
`500`	Internal Error	Something went wrong on our end	Contact support
`502`	Bad Gateway	Gateway/proxy error	Retry or contact support
`503`	Service Unavailable	Temporary service issue	Wait and retry

5xx errors are on us! If you see these consistently, please contact support with your requestId.

Getting Help

Contact Support

When contacting support, please include:

Request ID from the error response

Endpoint you were trying to access

Error response details available

Timestamp when the error occurred

Overview

API Endpoints

Error Response Structure

Response Fields

Quick Reference

Most Common

Format Issue

Not Found

Permissions

Complete Error Reference

Authentication Errors

Authorization Errors

HTTP Status Code Reference

Getting Help

Contact Support

​Error Response Structure

​Response Fields

​Quick Reference

Most Common

Format Issue

Not Found

Permissions

​Complete Error Reference

​Authentication Errors

​Authorization Errors

​HTTP Status Code Reference

​Getting Help

Contact Support

Error Response Structure

Response Fields

Quick Reference

Complete Error Reference

Authentication Errors

Authorization Errors

HTTP Status Code Reference

Getting Help