> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-authentication-and-errors.md). # REST API authentication and errors Credentials, error body, read-only tokens, and the rate-limit response of the REST API v1. Use this reference when you need exact information about how the REST API v1 accepts a credential and how it reports an error. ## Base URL and format | Item | Value | | ---------------- | ------------------------------------------ | | Base URL | `https://app.podigee.com/api/v1` | | Request body | JSON | | Response body | JSON | | Message language | English, independent of the account locale | ## Credentials | Credential | Where you get it | How you send it | | ------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- | | Account API key | **My account**, **API** tab, field **API key** | Header `Token: ` or `Authorization: Bearer ` | | Legacy REST API token (`pdg_pat_...`) | **My account**, **API** tab, **Create legacy REST API token** | Header `Token: ` or `Authorization: Bearer ` | | OAuth 2.0 access token | Granted to a partner application that Podigee registered | Header `Authorization: Bearer ` | The API reads the `Token` header first and the `Authorization` header second. The REST API does not accept Model Context Protocol (MCP) credentials. The API refuses an MCP connector credential with `401` and the message `This MCP credential is not valid for the legacy API.` The API treats an MCP personal access token as unknown and refuses it with the generic `401` body. Create a legacy REST API token instead. ## Access rules | Rule | Effect | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API access in the plan | Legacy REST API tokens work only when the plan includes API access: Scale and above, or an older plan that includes it. | | Organization members | The plan of the organization owner decides the API access. | | Subscription state | The API refuses requests when the subscription is canceled or suspended. The API also refuses legacy REST API tokens when the trial is expired. | | Podcast visibility | A credential sees the podcasts that its account owns, edits as a collaborator, or can see as an organization member. | | Read-only tokens | The API refuses a legacy REST API token with the scope **Read** on every request except `GET` and `HEAD`. The response is `403` with the message `This token is read-only.` | ## Error body Every error returns a JSON object with `code` and `message`. The `code` repeats the HTTP status. | Status | Body | When | | ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | `{"code": 401, "message": "You are not authorized to access this area.", "reason": "..."}` | Missing or wrong credential, no API access in the plan, or a suspended subscription. The `reason` names the cause: unknown user, API access not available, or suspended subscription. | | `403` | `{"code": 403, "message": "..."}` | The credential is valid but the action is not allowed, for example a read-only token on a write request. | | `404` | `{"code": 404, "message": "The with id could not be found."}` | The object does not exist or is not visible to the credential. | | `422` | `{"code": 422, "message": "..."}` | Validation failed. The message repeats the validation text. | | `500` | `{"code": 500, "message": "..."}` | Unhandled server error. Repeat the request later. | ## Rate limits The API counts the requests of each credential per minute. This page does not list the number of requests that your plan allows. When a credential sends more requests than allowed, the API responds as follows: | Item | Value | | ---------------------------- | -------------------------------------------------------------- | | Status | `429` | | Body | `Throttled` | | `RateLimit-Limit` header | The number of requests that the credential can send per minute | | `RateLimit-Remaining` header | `0` | | `RateLimit-Reset` header | When the current minute ends | | `Retry-After` header | The number of seconds to wait before the next request | Wait for the time in `Retry-After` before you send the next request. Requests that the web app sends with your browser session do not count against the limit of your credential. The three upload URL endpoints (`POST /uploads`, `POST /uploads/part_url`, `POST /uploads/complete_multipart_url`) have their own, higher limit for the account API key and OAuth access tokens. A client that Podigee blocked receives `503` with a message that asks you to contact Podigee Support if you think the block is an error. ## Field filter on list endpoints Add `fields_filter[]=` one or more times to a list request to receive only the named fields. The API always includes `id` and `title`. ## Related tasks * [Get your API key or token](/documentation/connect-and-administer/integrations/get-your-api-key-or-token.md) * [Make your first API request](/documentation/connect-and-administer/integrations/rest-api/make-your-first-api-request.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-authentication-and-errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.