Error Handling

All API errors return a consistent JSON structure with an error object containing a machine-readable code and human-readable message.

Error Response Format

Every error response follows this structure:

{
  "object": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "details": {
      // Optional additional context
    },
    "documentationUrl": "https://docs.mapademics.com/errors/error-code"
  }
}

Field	Type	Description
code	string	Machine-readable error code (use for programmatic handling)
message	string	Human-readable error description
details	object	Optional field-level details or additional context
documentationUrl	string	Link to relevant documentation

Error Codes by HTTP Status

400 Bad Request

Invalid request parameters or malformed input.

Error Code	Description
INVALID_INPUT	Request parameters failed validation
MISSING_REQUIRED_FIELD	A required field was not provided
INVALID_FORMAT	A field has an invalid format

Example: Invalid CIP Code Format

{
  "object": "error",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid CIP code format. Expected format: XX.XXXX",
    "details": {
      "field": "cipCode",
      "provided": "110701",
      "expected": "XX.XXXX"
    },
    "documentationUrl": "https://docs.mapademics.com/errors/invalid-input"
  }
}

401 Unauthorized

Missing or invalid authentication credentials.

Error Code	Description
UNAUTHORIZED	Missing or invalid API key
INVALID_API_KEY	API key format is correct but key doesn't exist
EXPIRED_API_KEY	API key has been revoked or expired

Example: Missing API Key

{
  "object": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid X-API-Key header",
    "documentationUrl": "https://docs.mapademics.com/authentication"
  }
}

403 Forbidden

Valid authentication but insufficient permissions.

Error Code	Description
FORBIDDEN	API key doesn't have access to this resource
QUOTA_EXCEEDED	Monthly quota has been exceeded
FEATURE_NOT_ENABLED	Feature not available on your plan

Example: Feature Not Enabled

{
  "object": "error",
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have access to the Syllabus Skills Extraction API",
    "documentationUrl": "https://docs.mapademics.com/permissions"
  }
}

404 Not Found

The requested resource doesn't exist.

Error Code	Description
NOT_FOUND	Resource not found
CIP_NOT_FOUND	CIP code not in database
SOC_NOT_FOUND	SOC code not in database
SKILL_NOT_FOUND	Skill ID doesn't exist
TASK_NOT_FOUND	Extraction task doesn't exist

Example: CIP Code Not Found

{
  "object": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "CIP code '99.9999' not found",
    "documentationUrl": "https://docs.mapademics.com/errors/not-found"
  }
}

429 Rate Limited

Too many requests in the current time window.

Error Code	Description
RATE_LIMITED	Request rate limit exceeded

Rate limit responses include additional headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining (will be 0)
X-RateLimit-Reset	Unix timestamp when limit resets
Retry-After	Seconds until you can retry

Example: Rate Limit Exceeded

{
  "object": "error",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "limit": 1000,
      "window": "1 hour",
      "resetAt": "2025-01-30T13:00:00Z"
    },
    "documentationUrl": "https://docs.mapademics.com/rate-limits"
  }
}

500 Internal Error

An unexpected error occurred on our servers.

Error Code	Description
INTERNAL_ERROR	Unexpected server error

Example: Internal Error

{
  "object": "error",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "details": {
      "requestId": "req_xyz789abc"
    },
    "documentationUrl": "https://docs.mapademics.com/errors/internal-error"
  }
}

Always include the requestId when contacting support about internal errors. This helps us quickly locate the issue in our logs.

Handling Errors in Code

TypeScript Example

interface MapademicsError {
  object: "error";
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
    documentationUrl?: string;
  };
}

async function fetchLaborMarketData(cipCode: string, customerId: string) {
  const response = await fetch(
    `https://embedded-api.mapademics.com/v1/labor-market-intelligence/cip/${cipCode}`,
    {
      headers: {
        "X-API-Key": process.env.MAPADEMICS_LIVE_KEY!,
        "X-End-Customer-API-Key": customerId,
      },
    }
  );

  if (!response.ok) {
    const error: MapademicsError = await response.json();

    switch (error.error.code) {
      case "UNAUTHORIZED":
        throw new Error("Invalid API key. Check your configuration.");

      case "NOT_FOUND":
        throw new Error(`CIP code ${cipCode} not found.`);

      case "RATE_LIMITED":
        const retryAfter = response.headers.get("Retry-After");
        throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`);

      case "INTERNAL_ERROR":
        console.error("Mapademics API error:", error.error.details?.requestId);
        throw new Error("Service temporarily unavailable. Please try again.");

      default:
        throw new Error(error.error.message);
    }
  }

  return response.json();
}

Python Example

import requests
import time

class MapademicsAPIError(Exception):
    def __init__(self, code, message, details=None, request_id=None):
        self.code = code
        self.message = message
        self.details = details
        self.request_id = request_id
        super().__init__(message)

def fetch_labor_market_data(cip_code: str, customer_id: str):
    response = requests.get(
        f"https://embedded-api.mapademics.com/v1/labor-market-intelligence/cip/{cip_code}",
        headers={
            "X-API-Key": os.environ["MAPADEMICS_LIVE_KEY"],
            "X-End-Customer-API-Key": customer_id
        }
    )

    if not response.ok:
        error = response.json()["error"]

        if error["code"] == "RATE_LIMITED":
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            return fetch_labor_market_data(cip_code)  # Retry

        raise MapademicsAPIError(
            code=error["code"],
            message=error["message"],
            details=error.get("details"),
            request_id=error.get("details", {}).get("requestId")
        )

    return response.json()

Troubleshooting

For detailed troubleshooting steps and common solutions, see the FAQ & Common Issues page.

Getting Help

If you're stuck, contact support with:

1. Request ID from the error response

2. Timestamp of when the error occurred

3. Endpoint you were calling

4. Request body (sanitize any sensitive data)

Email: [email protected]