Errors

Common error responses, what they mean, and how to handle them when integrating with the Mapademics Embedded API.

When an API request fails, the Mapademics Embedded API returns an error response with an appropriate HTTP status code and a structured JSON error object.

This page describes common error responses, typical causes, and actionable remediation steps.

---

Error response format

All error responses use this JSON structure:

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

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

Always inspect both code and message when handling errors programmatically.

---

Authentication and authorization errors

401 Unauthorized

What it means

Your request is missing a valid platform API key or the key is malformed.

Typical causes

• Missing Authorization header

• Typo in the API key

• Using a test key in production (or vice versa)

• API key has been revoked or expired

How to fix it

Ensure you include:

Authorization: Bearer YOUR_PLATFORM_API_KEY

Double-check the environment (test vs production).

Example response

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

---

403 Forbidden

What it means

The request is authenticated, but the customer key is missing, invalid, or not authorized for this customer context.

Typical causes

• Missing X-Customer-Key header

• Using a platform key in place of a customer key

• Using a customer key that belongs to a different partner

• Customer has been deleted

How to fix it

Include:

X-Customer-Key: YOUR_CUSTOMER_API_KEY

Verify the customer key is valid and belongs to your partner account.

Example response

{
  "object": "error",
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing or invalid end-customer key",
    "documentationUrl": "https://docs.mapademics.com/authentication"
  }
}

---

Client errors

400 Bad Request

What it means

The request payload is malformed or missing required fields.

Typical causes

• Missing required field (e.g., cipCodes)

• Invalid data type (e.g., string instead of array)

• Bad JSON syntax

• Invalid format (e.g., CIP code without period)

How to fix it

• Validate your payload against the API specification

• Use proper JSON formatting

• Check field types and formats

Example response

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

---

404 Not Found

What it means

The requested resource does not exist.

Typical causes

• Invalid extraction ID or task ID

• Typo in endpoint URL

• CIP or SOC code not in database

• Skill ID doesn't exist

How to fix it

• Confirm the resource identifier exists

• Confirm the correct endpoint path

• Check for typos in IDs

Example response

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

---

409 Conflict

What it means

The request conflicts with an existing resource.

Typical causes

• Creating a customer with a name that already exists

• Duplicate resource creation

How to fix it

• Use a unique name or identifier

• Check if the resource already exists before creating

Example response

{
  "object": "error",
  "error": {
    "code": "CONFLICT",
    "message": "A customer with this name already exists",
    "documentationUrl": "https://docs.mapademics.com/errors/conflict"
  }
}

---

Rate limits

429 Too Many Requests

What it means

The customer has exceeded the allowed rate limit.

Typical causes

• High request frequency without caching

• Repeated syllabus extraction loops

• No backoff on retry

• Calling labor market endpoints on every page view

How to fix it

• Respect rate-limit headers (X-RateLimit-Remaining, X-RateLimit-Reset)

• Cache heavily for labor market data

• Persist and reuse extraction jobs

• Implement exponential backoff

Example response

{
  "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"
  }
}

The response also includes 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

---

Server errors

500 Internal Server Error

What it means

An unexpected error occurred on the server.

How to fix it

• Retry with exponential backoff

• Contact support with the requestId if the issue persists

Example response

{
  "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.

---

502 / 503 / 504

What it means

Transient server or infrastructure errors.

How to fix it

• Retry with exponential backoff and jitter

• Do not retry indefinitely

• These are typically temporary and resolve quickly

---

Best practices for handling errors

Retry patterns

• Retry only idempotent requests automatically

• Use exponential backoff with jitter

• Respect X-RateLimit-Reset and Retry-After headers

• Set a maximum retry count

UX patterns

• Surface human-friendly messages for users

• Offer retry controls when appropriate

• Log and report requestId for support debugging

---

Monitoring customer usage

You can query a customer's current usage and rate-limit state:

GET /customers/{customerId}/usage

This helps you:

• Build admin dashboards

• Detect approaching limits

• Proactively throttle to avoid 429 responses

• Debug unexpected rate limit issues

---

Example handling logic

async function handleApiResponse(response) {
  if (response.ok) {
    return response.json();
  }

  const { error } = await response.json();

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

    case "FORBIDDEN":
      throw new Error("Access denied. Check your customer key.");

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

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

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

---

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]

---

Related documentation

• Rate limits

• Authentication

• API reference