# Errors & billing

What each status code means, how to fix it - and how plans, included requests and overage are billed.

- [Job Postings API](#jobs)
- [Job Postings RSS Feed API](#rss)

## Job Postings API

### Errors

All errors return JSON with a `message` field.

| Status | Cause | Solution |
|---|---|---|
| **400** Bad Request | A parameter value could not be parsed, e.g. an unknown `countryCode`, an invalid date or `sort` value. | Check the value against the parameter description. The `message` names the invalid parameter. |
| **401** Unauthorized | The key is missing or invalid, or the request was sent directly to the backend instead of RapidAPI. | Send your key in the header `X-RapidAPI-Key` and use the base URL `https://daily-international-job-postings.p.rapidapi.com`. Copy the key again from the RapidAPI listing if it was rotated. |
| **403** Forbidden | Either you are not subscribed to this API ("You are not subscribed to this API."), or the endpoint is not included in your plan (e.g. `/api/v2/meta/jobs/distinct` and `/api/v2/meta/jobs/statistics` need at least the Pro plan). | Subscribe to the Basic plan, or upgrade to the plan named in `requiredPlan`. The response contains `message`, `requiredPlan` and `pricingUrl`. |
| **404** Not Found | The endpoint path does not exist (typo, wrong API version) or a required search parameter is missing, or the requested `field` does not exist. | Check the path and add at least one search parameter (e.g. `countryCode`). The `message` lists the allowed parameters or fields. |
| **405** Method Not Allowed | Another HTTP method than GET was used. | Use GET. |
| **429** Too Many Requests | Too many requests in a short time window (rate limit of your RapidAPI plan, e.g. 1 request/second on Basic). This is **not** a monthly limit - the plans have no hard limit, extra requests are billed as overage. RapidAPI also answers 429 after repeated calls with an invalid key. | Slow down and retry with exponential backoff (e.g. 1 s, 2 s, 4 s). If it persists, check that your key is valid. |
| **500** Internal Server Error | An unexpected error on our side. | Retry once. If it persists, contact data@techmap.io with the full request URL (without your key). |
| **502/504** Bad Gateway / Gateway Timeout | RapidAPI did not get a timely answer from the backend, typically for very broad queries. | Narrow the query (more filters, shorter date range) and retry. |
| **503** Service Unavailable | The search backend is temporarily unavailable. | Retry later with exponential backoff. |
| **509** Bandwidth Limit Exceeded | The response would be larger than 6 MB. | Request a more compact `format` or narrow the query. |

#### Example: endpoint not included in your plan (403)

```json
{
  "message": "Forbidden request to the API - this endpoint is not included in your plan. It is included from the Pro plan on.",
  "requiredPlan": "Pro",
  "pricingUrl": "https://rapidapi.com/techmap-io-techmap-io-default/api/daily-international-job-postings/pricing"
}
```

### Billing & overage

#### RapidAPI

- **Included:** every plan includes a number of requests per month (Basic, Pro, Ultra, Mega).
- **Above the quota:** requests are **not blocked**. Each additional request is billed as **overage** at the per-request price of your plan. There is no hard limit, so you never get a "limit reached" error.
- **When a bigger plan is cheaper:** as soon as your monthly overage costs more than the price difference to the next plan. Break-even = included requests + (price of next plan - price of your plan) / overage price per request.
- **Current prices and quotas:** [RapidAPI pricing page](https://rapidapi.com/techmap-io-techmap-io-default/api/daily-international-job-postings/pricing)

| Plan | Price / month | Included requests | Postings per request | Included postings | Each additional request | Rate limit | Next plan is cheaper above |
|---|---|---|---|---|---|---|---|
| Basic | $0 | 100 | 10 | 1,000 | $0.06 | 1 request/second | 5,834 postings / month |
| Pro | $29 | 3,000 | 10 | 30,000 | $0.04 | 2 requests/second | 47,501 postings / month |
| Ultra | $99 | 10,000 | 10 | 100,000 | $0.02 | 5 requests/second | 200,001 postings / month |
| Mega | $299 | 30,000 | 10 | 300,000 | $0.01 | 10 requests/second | - |

Example: with the Basic plan, 5,834 postings (584 requests) a month cost $0 + 484 × $0.06 = $29.04 - from then on the Pro plan ($29) is cheaper.

Prices as listed on RapidAPI; the [pricing page](https://rapidapi.com/techmap-io-techmap-io-default/api/daily-international-job-postings/pricing) is authoritative. RapidAPI may add a bandwidth fee for very large transfers.

The endpoints `/api/v2/meta/jobs/distinct` and `/api/v2/meta/jobs/statistics` are included from the **Pro** plan on. With a smaller plan they return **403** with `requiredPlan` and `pricingUrl`.

## Job Postings RSS Feed API

### Errors

All errors return JSON with a `message` field.

| Status | Cause | Solution |
|---|---|---|
| **400** Bad Request | A parameter value could not be parsed, e.g. an unknown `countryCode` or an invalid date. | Check the value against the parameter description. The `message` names the invalid parameter. |
| **401** Unauthorized | The key is missing or invalid, or the request was sent directly to the backend instead of RapidAPI. | Send your key in the query parameter `rapidapi-key` and use the base URL `https://job-postings-rss-feed.p.rapidapi.com`. Copy the key again from the RapidAPI listing if it was rotated. |
| **403** Forbidden | You are not subscribed to this API ("You are not subscribed to this API."). | Subscribe to the Basic plan. |
| **404** Not Found | The endpoint path does not exist (typo, wrong API version) or a required search parameter is missing. | Check the path and add at least one search parameter (e.g. `countryCode`). The `message` lists the allowed parameters. |
| **405** Method Not Allowed | Another HTTP method than GET was used. | Use GET. |
| **429** Too Many Requests | Too many requests in a short time window (rate limit of your RapidAPI plan, e.g. 1 request/second on Basic). This is **not** a monthly limit - the plans have no hard limit, extra requests are billed as overage. RapidAPI also answers 429 after repeated calls with an invalid key. | Slow down and retry with exponential backoff (e.g. 1 s, 2 s, 4 s). If it persists, check that your key is valid. |
| **500** Internal Server Error | An unexpected error on our side. | Retry once. If it persists, contact data@techmap.io with the full request URL (without your key). |
| **502/504** Bad Gateway / Gateway Timeout | RapidAPI did not get a timely answer from the backend, typically for very broad queries. | Narrow the query (more filters, shorter date range) and retry. |
| **503** Service Unavailable | The search backend is temporarily unavailable. | Retry later with exponential backoff. |
| **509** Bandwidth Limit Exceeded | The response would be larger than 6 MB. | Use a smaller `pageSize` or narrow the query. |

### Billing & overage

#### RapidAPI

- **Included:** every plan includes a number of requests per month (Basic, Pro, Ultra, Mega).
- **Above the quota:** requests are **not blocked**. Each additional request is billed as **overage** at the per-request price of your plan. There is no hard limit, so you never get a "limit reached" error.
- **When a bigger plan is cheaper:** as soon as your monthly overage costs more than the price difference to the next plan. Break-even = included requests + (price of next plan - price of your plan) / overage price per request.
- **Current prices and quotas:** [RapidAPI pricing page](https://rapidapi.com/techmap-io-techmap-io-default/api/job-postings-rss-feed/pricing)

| Plan | Price / month | Included requests | Postings per request | Included postings | Each additional request | Rate limit | Next plan is cheaper above |
|---|---|---|---|---|---|---|---|
| Basic | $0 | 100 | 10 | 1,000 | $0.06 | 1 request/second | 5,834 postings / month |
| Pro | $29 | 3,000 | 10 | 30,000 | $0.04 | 1 request/second | 47,501 postings / month |
| Ultra | $99 | 1,000 | 100 | 100,000 | $0.20 | 1 request/second | 200,001 postings / month |
| Mega | $299 | 300 | 1,000 | 300,000 | $1 | 1 request/second | - |

Example: with the Basic plan, 5,834 postings (584 requests) a month cost $0 + 484 × $0.06 = $29.04 - from then on the Pro plan ($29) is cheaper.

Prices as listed on RapidAPI; the [pricing page](https://rapidapi.com/techmap-io-techmap-io-default/api/job-postings-rss-feed/pricing) is authoritative. RapidAPI may add a bandwidth fee for very large transfers.