FAQ & Common Issues

Common questions and troubleshooting for the Mapademics Embedded API.

Authentication Issues

"401 Unauthorized" error

Your API key is missing or invalid. Check the following:

1. Include the correct headers:

   • Testing: X-API-Key header with your pk_test_xxx key

   • Production: Both X-API-Key (with pk_live_xxx) AND X-End-Customer-API-Key headers

2. Verify key format:

   • Primary keys start with pk_test_ or pk_live_

   • End-customer keys start with ck_

3. Check for formatting issues:

   • No extra spaces or quotes around the key

   • Key hasn't been revoked in the portal

# Testing (only X-API-Key required)
curl -X GET "https://embedded-api.testing.mapademics.com/v1/skills" \
  -H "X-API-Key: pk_test_xxx"

# Production (both headers required)
curl -X GET "https://embedded-api.mapademics.com/v1/skills" \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-End-Customer-API-Key: ck_xxx"

"403 Forbidden" error

Your API key is valid but doesn't have access to this resource. Possible causes:

• Missing end-customer key: Production calls require both X-API-Key and X-End-Customer-API-Key

• Feature not enabled: Some endpoints may not be available on your plan

• Quota exceeded: You've exceeded your monthly quota

Contact [email protected] if you need access to additional features.

API Keys

How do I get API keys?

Contact [email protected] to get access to the Embedded API Portal, where you can view your keys and provision end-customer keys.

What's the difference between test and live keys?

Aspect	Test (pk_test_xxx)	Live (pk_live_xxx)
Environment	embedded-api.testing.mapademics.com	embedded-api.mapademics.com
End-customer key required	No	Yes
Data	Sample/synthetic	Real
Rate limits	Higher (for development)	Standard
Billing	Not billed	Billed per request

What are end-customer API keys?

End-customer keys (ck_xxx) identify which of your customers is making the API call. They enable:

• Per-customer usage tracking

• Per-customer rate limits

• Customer-specific billing

You provision end-customer keys in the Embedded API Portal.

How do I rotate my API keys?

1. Log into the Embedded API Portal

2. Navigate to API Keys

3. Generate a new key

4. Update your application

5. Revoke the old key

What should I do if my key is compromised?

1. Immediately revoke the key in the Embedded API Portal

2. Generate a new key

3. Update your application

4. Contact [email protected] to review usage logs

Rate Limits

How can I increase my rate limits?

1. First, implement best practices (caching, batching)

2. Monitor your usage patterns

3. Contact [email protected] to discuss your needs

I'm getting "429 Too Many Requests" errors

You've exceeded your rate limit. The response includes a Retry-After header telling you how long to wait. See Rate Limits for implementation details on exponential backoff.

Data & Formats

Invalid CIP/SOC code format

CIP codes must be in XX.XXXX format:

• Correct: 11.0701

• Wrong: 110701, 11-0701, 11.071

SOC codes must be in XX-XXXX format:

• Correct: 15-1252

• Wrong: 151252, 15.1252, 15-125

Resource not found but I know it exists

1. Check the code format (see above)

2. Verify the code is in our database - not all codes have data

3. Try the regions endpoint to check data availability by region

Syllabus Skills Extraction

Extraction task failed

Common extraction errors:

Error Code	Cause	Solution
DOCUMENT_PARSE_ERROR	Unable to read the file	Ensure PDF isn't corrupted or password-protected
UNSUPPORTED_FORMAT	File type not supported	Use PDF or DOCX format
DOCUMENT_TOO_LARGE	File exceeds size limit	Keep files under 25MB
NO_TEXT_FOUND	Document appears to be image-only	Ensure PDF has extractable text (not scanned images)

SDKs & Tools

Do you offer SDKs?

Official SDKs are on our roadmap. In the meantime, you can:

• Use the OpenAPI spec to generate clients

• Use the code examples in our documentation

• Implement direct HTTP calls

Getting Help

If you can't find the answer here:

1. Check the Error Handling guide for detailed error codes

2. Email [email protected] with:

   • Your requestId from the error response

   • Timestamp of when the error occurred

   • The endpoint you were calling

   • The full error response