Skip to main content

​
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

FieldTypeDescriptionExample
codestring🏷️ Internal error code for categorization"4300", "4030"
httpMethodstring🌐 HTTP method used in the request"GET", "POST", "PATCH"
messagestring💬 Human-readable error description"Missing authentication token"
pathstring🛣️ Exact API endpoint path that was called"/onboarding/api/v1/users/all"
requestIdstring🔍 Unique identifier for this request (UUID)"46a7ad4b-c315-441c-ad2c-473f4075e1b5"
resourcePathstring⚙️ 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 FieldDetails
HTTP Status403 Forbidden
MessageMissing authentication token
Root CauseNo 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: your_api_key_here" \
     -H "Content-Type: application/json" \
     https://api.carbnconnect.com/onboarding/api/v1/users/all
Response FieldDetails
HTTP Status403 Forbidden
MessageInvalid API key format
Root CauseAPI 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)
Response FieldDetails
HTTP Status401 Unauthorized
MessageAPI key not found
Root CauseAPI 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.
Response FieldDetails
HTTP Status401 Unauthorized
MessageAPI key has expired
Root CauseAPI 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
Response FieldDetails
HTTP Status401 Unauthorized
MessageAPI key is inactive
Root CauseAPI 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 FieldDetails
HTTP Status403 Forbidden
MessageInsufficient permissions to access resource
Root CauseYour 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 CodeStatus NameDescriptionAction Required
200OKYour request has completed successfullyNo action required
201CreatedResource created successfullyNo action required
2xx responses indicate successful requests. Your API call worked as expected and you can proceed with the response data.
Status CodeStatus NameDescriptionAction Required
400Bad RequestRequest format is invalid or malformedFix request syntax
401UnauthorizedAuthentication failed or missing credentialsCheck API key
403ForbiddenAccess forbidden due to permissionsCheck permissions
404Not FoundResource doesn’t exist or not foundVerify resource ID
429Rate LimitedToo many requests sent recentlyWait and retry
4xx errors mean there’s an issue with your request. Double-check your API key, request format, and permissions.
Status CodeStatus NameDescriptionAction Required
500Internal ErrorSomething went wrong on our endContact support
502Bad GatewayGateway/proxy errorRetry or contact support
503Service UnavailableTemporary service issueWait 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