Authentication

API Key

All requests require an API key. You can pass it in two ways:

Header (recommended)

X-API-Key: your-api-key-here

Bearer token

Authorization: Bearer your-api-key-here

Both methods are equivalent. Use whichever fits your HTTP client.

Rate Limits

Every client has two limits:

Limit	Default	Description
Per-minute	100 req/min	Sliding window, resets every minute
Monthly quota	10,000 req/month	Calendar month, resets on the 1st

Rate limit headers

Every response includes these headers:

Header	Description
X-RateLimit-Limit	Your per-minute limit
X-RateLimit-Remaining	Requests left in this minute
X-RateLimit-Reset	ISO 8601 timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

Handling 429 responses

When you exceed the rate limit, you'll get a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded. Retry after 45 seconds."
}

Best practice: Read the Retry-After header and wait that many seconds before retrying. Do not retry immediately.

import time
import requests

response = requests.get(url, headers={"X-API-Key": api_key})
if response.status_code == 429:
    wait = int(response.headers.get("Retry-After", 60))
    time.sleep(wait)
    response = requests.get(url, headers={"X-API-Key": api_key})

Error Responses

All errors return a JSON object with an error field:

Status	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — account suspended or inactive
404	Not found — resource doesn't exist
409	Conflict — EVSE not available for requested time
429	Rate limited — too many requests
500	Server error — contact support

Example error response:

{
  "error": "Invalid latitude: must be between -90 and 90"
}

Checking Your Usage

Use the /usage endpoint to check your current rate limit and quota status:

curl -s https://api.petitmonde.energy/api/v1/client/usage \
  -H "X-API-Key: YOUR_API_KEY" | jq .

{
  "rate_limit": {
    "limit": 100,
    "remaining": 87,
    "period": "minute",
    "reset_at": "2026-02-10T10:01:00Z"
  },
  "monthly_quota": {
    "limit": 10000,
    "used": 3456,
    "remaining": 6544,
    "period": "month",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28"
  }
}

Security

• API keys are hashed (bcrypt) on our side — we cannot retrieve a lost key
• Keys are shown once at creation time. Store them securely (e.g., environment variables, secrets manager)
• Do not commit API keys to version control
• If a key is compromised, contact your account manager for rotation