Errors | PASTOR Docs

All error responses from the PASTOR API use HTTP status codes and a consistent JSON body.

Error response format

{
  "error": {
    "code": "MUNICIPALITY_NOT_FOUND",
    "message": "No municipality found with municipio_id '99999'.",
    "param": "municipio_id",
    "request_id": "req_abc123"
  }
}

Field	Description
`code`	Machine-readable error identifier. Use this in your error handling logic.
`message`	Human-readable description of the error. Do not parse this string programmatically — it may change.
`param`	The request parameter that caused the error, if applicable.
`request_id`	Include this when contacting support about a specific failed request.

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded.
`400 Bad Request`	The request was malformed. Check the `param` field for the offending parameter.
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	The token does not have permission to access the requested municipality.
`404 Not Found`	The requested municipality does not exist.
`422 Unprocessable Entity`	The request was well-formed but the parameter values were invalid (e.g. a date outside the supported range).
`429 Too Many Requests`	Rate limit exceeded. Check `Retry-After` and `X-RateLimit-Reset` headers.
`500 Internal Server Error`	Unexpected server error. Contact developers@pastormap.com if the error persists.
`503 Service Unavailable`	Scheduled maintenance or temporary outage. See pastormap.com/status.

Error code catalog

Authentication errors

Code	Status	Description
`MISSING_AUTH_HEADER`	401	The `Authorization` header was not included in the request.
`INVALID_API_KEY`	401	The token is malformed, expired or has been revoked. Contact developers@pastormap.com.
`INSUFFICIENT_SCOPE`	403	The token does not have permission to access the requested municipality. Contact developers@pastormap.com to adjust access.

Parameter errors

Code	Status	Description
`MISSING_REQUIRED_PARAM`	400	A required parameter was not provided. See `param` for which one.
`INVALID_PARAM_FORMAT`	400	A parameter value did not match the expected format (e.g. a date not in YYYY-MM-DD format).
`MUNICIPALITY_NOT_FOUND`	404	The `municipio_id` does not match any municipality in the PASTOR database.
`DATE_OUT_OF_RANGE`	422	The requested date is before 2015-01-01 (earliest available data) or in the future.
`DATE_RANGE_TOO_LARGE`	422	The date range span exceeds the maximum allowed for this endpoint.

Report errors

Code	Status	Description
`REPORT_NOT_FOUND`	404	No report exists with the given ID, or it belongs to a different account.
`REPORT_EXPIRED`	410	The report was generated more than 12 months ago and is no longer available.
`REPORT_FAILED`	500	The report generation job failed. Retry the `POST /api/v1/report` request.
`UNSUPPORTED_FORMAT`	422	The requested format is not available for the selected report type.

Retry strategy

For 500 and 503 errors, retry with exponential backoff starting at 1 second:

import time, requests

def request_with_retry(url, headers, max_retries=4):
    delay = 1
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code not in (500, 503):
            return resp
        if attempt < max_retries - 1:
            time.sleep(delay)
            delay = min(delay * 2, 30)
    return resp

Do not retry 4xx errors — they indicate problems with your request that will not resolve on their own.