Error reference
This page lists every user-facing error the PinBridge API returns, grouped by HTTP status. Each row gives the error_code or detail string, what causes it, and how to fix it. Use it alongside Troubleshooting when you hit a problem, and My pin failed for pin-level error_codes that show up on a pin instead of an HTTP response.
Error response shapes
PinBridge returns two response shapes depending on the error.
Billing errors (402) use a nested envelope:
{
"error": {
"code": "quota_exceeded",
"message": "Monthly pin creation quota (1000) exceeded. Current usage: 1000.",
"upgrade_url": "/v1/billing/checkout"
}
}
upgrade_url points to where you resolve the problem. It can be null (for example, on Agency and Enterprise plans, where there is no self-serve upgrade). All 402 responses use this shape.
Everything else uses FastAPI’s standard shape. Most errors carry a plain detail:
{ "detail": "Pin not found" }
Some 403 errors add structured fields (for example permission, current_count, or required_plan) alongside the message. Validation errors (422) return FastAPI’s array of field errors under detail. Uncaught server errors (500) also include a request_id:
{ "detail": "Internal server error", "request_id": "..." }
Placeholders below: $PINBRIDGE_API_KEY for your key, 6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41 / 987654321098765432 for IDs.
400 Bad Request
The request was understood but a value is not acceptable. Fix the value and retry.
| Detail string | Cause | Fix |
|---|---|---|
run_at must be in the future |
A schedule (or an import row with run_at) is set to a past time. |
Send a future ISO 8601 timestamp with a timezone offset. |
cover_image_url is only supported for video pins |
You set a cover image on an image pin. | Remove the cover field, or reference a video asset_id so the pin is a video pin. |
Cannot cancel schedule with status <s> |
The schedule is not in a cancelable state. | Only pending schedules can be canceled. Check the current status first. |
Cannot retry schedule with status <s> |
The schedule is not in a retryable state. | Only failed schedules can be retried. |
Cannot delete schedule with status <s>; cancel it first. |
You tried to delete a schedule that must be canceled first. | Cancel the schedule, then delete it. |
Unsupported image content type |
The image is not gif, jpeg, png, or webp. | Upload a supported image format. |
Unsupported video content type |
The video is not mp4 or quicktime. | Upload an mp4 or quicktime (.mov) file. |
Uploaded file is empty |
The uploaded file has zero bytes. | Re-upload a valid, non-empty file. |
Uploaded <type> exceeds the maximum allowed size |
The file is over the size limit (global path). | See the plan-based per-file limits and reduce file size. See My video upload failed. |
file_too_large — File exceeds the maximum allowed size of <N> MB for your plan. |
The file is over your plan’s per-file limit. | Compress the file or upgrade your plan. See My video upload failed. |
Invalid OAuth state |
The Pinterest connect callback state did not match. | Restart the connect flow from PinBridge. See My Pinterest account got disconnected. |
CSV is missing required columns: ... |
The CSV lacks account_id, board_id, title, or idempotency_key. |
Add the required columns. |
CSV contains unsupported columns: ... |
The CSV has a column outside the allowed set. | Remove the extra columns. |
Import exceeds the maximum of 500 rows |
The import has more than 500 rows. | Split the import into batches of 500 or fewer. |
Invalid invitation link. |
The team invite token is malformed. | Request a fresh invitation. |
This invitation has been revoked. |
The invite was revoked before you accepted. | Ask the org owner or admin to re-invite you. |
This invitation has expired. |
The invite passed its expiry window. | Ask for a new invitation. |
Invalid or expired password reset token |
The reset link is used, expired, or wrong. | Request a new password reset. |
Current password is incorrect |
The password change supplied the wrong current password. | Re-enter your current password. |
New password must be different from current password |
The new password matches the old one. | Choose a different password. |
New email must be different from your current email. |
The email change used the same email. | Enter a different email address. |
Invalid or expired verification token |
The email verification link is used, expired, or wrong. | Resend the verification email. |
Invalid or expired email change confirmation link |
The email-change confirmation link is used, expired, or wrong. | Restart the email change. |
Workspace name cannot be empty |
A blank project (workspace) name was submitted. | Provide a non-empty name. |
Country must be a 2-letter ISO code |
The country field is not a valid ISO 3166 code. | Send a two-letter code, for example US. |
401 Unauthorized
Authentication failed. Fix your credentials and retry.
| Detail string | Cause | Fix |
|---|---|---|
Missing API key. Provide X-API-Key or Authorization: Bearer <key>. |
No credential was sent. | Send your key in the X-API-Key header. See 401 Invalid API key. |
Invalid API key |
The key is unknown, revoked, or mistyped. | Recheck the key value and that it belongs to this project. See 401 Invalid API key. |
Invalid or missing access token |
A user-session (bearer) call had an invalid or missing token. | Sign in again to refresh the session token. |
Invalid access token |
The bearer token on an account endpoint (for example /v1/auth/me) is invalid. |
Sign in again. |
Invalid email or password |
Login credentials are wrong. | Recheck email and password, or reset your password. |
Team access requires a user session. |
A team endpoint was called with an API key instead of a bearer session. | Call team endpoints with a user-session JWT. |
Team access requires an organization session. |
The session is not scoped to an organization. | Switch into the organization, then retry. |
Current project is not linked to an organization |
The active project has no organization. | Link the project to an organization first. |
Note: X-API-Key works for all publishing and read endpoints. /v1/auth/me and /v1/projects require a user-session JWT and reject API keys.
402 Payment Required
Billing or quota blocks the request. All 402 responses use the {error:{code,message,upgrade_url}} envelope shown above.
code |
Cause | Fix |
|---|---|---|
billing_inactive |
Plan is not Free and billing status is not active or trialing (for example, a failed payment). Message: “Billing status is {status}. Please update payment method.” | Update your payment method. upgrade_url is the billing portal (/v1/billing/portal). |
quota_exceeded |
Your monthly pin quota is used up and credits do not apply. Message includes the limit and current usage. | Wait for the monthly reset, or upgrade. upgrade_url is /v1/billing/checkout (null on Agency and Enterprise). See 402 quota_exceeded. |
credits_exhausted |
Monthly quota is used up, credits are enabled, and your credit balance is 0. | Buy a credit pack. upgrade_url is /v1/billing/credits/purchase. See 402 quota_exceeded. |
storage_quota_exceeded |
Your organization’s disk quota is full during an asset upload. Message: “Organization storage quota exhausted. Delete files or upgrade your plan to continue uploading.” | Delete assets to free space, or upgrade. See My video upload failed. |
Monthly quota counts successful publishes and is consumed first; only after it is exhausted does PinBridge debit credits (1 credit per pin), if credits are enabled. Free and trial workspaces cannot buy or use credits.
403 Forbidden
You are authenticated, but your plan or role does not allow this action.
error_code / detail |
Cause | Fix |
|---|---|---|
feature_unavailable — Feature '<f>' not available on <plan> plan. |
A plan-gated feature (for example asset upload, bulk import) is off on your plan. upgrade_url is /v1/billing/checkout. |
Upgrade to a plan that includes the feature. See 403 plan_limit. |
plan_limit (Pinterest accounts) — Pinterest account limit (<n>) reached for <plan> plan. |
You hit your plan’s connected-account cap. Includes current_count. |
Disconnect an account or upgrade. See 403 plan_limit. |
plan_limit (API keys) — Active API key limit (<n>) reached for <plan> plan. |
You hit your plan’s active API key cap. | Revoke an unused key or upgrade. See 403 plan_limit. |
sandbox_limit — Pinterest account limit (<n>) reached for sandbox projects. |
You hit the sandbox project’s account cap. | Disconnect a sandbox account. |
plan_required — Team access is available on Agency and Enterprise plans. |
Team features require the Agency (pro) or Enterprise plan. required_plan is pro, upgrade_url is /pricing. |
Upgrade to Agency or Enterprise. |
insufficient_permissions |
Your role lacks the required permission. The response includes a permission field (for example can_publish, can_manage_members, can_manage_billing, can_manage_api_keys, can_manage_integrations, can_delete_assets, can_reset_sandbox, team_view). |
Ask an owner or admin to grant the permission or perform the action. |
trial_locked_pinterest_account — This Pinterest account has already been used to consume a PinBridge trial on another workspace. |
The Pinterest account was already used for a trial elsewhere. | Use a different Pinterest account, or a paid plan. |
sandbox_board_writes_disabled / sandbox_board_limit |
Board create or delete is disabled or capped in sandbox. | Board writes are off by default in sandbox. Do this in a live project. |
This invitation was sent to a different email address. |
You accepted an invite with a different account. | Sign in with the email the invite was sent to. |
Admin API access denied / Admin API host not allowed / Admin access denied |
An admin-only endpoint was called without admin access or from a disallowed host. | These endpoints are for platform admins only. |
404 Not Found
The referenced resource does not exist, is not in your project, or was deleted.
| Detail string | Cause | Fix |
|---|---|---|
Pin not found |
The pin ID is wrong, deleted, or in another project. | Check the pin ID and that you are using the right project’s key. |
Import job not found |
The import job ID is wrong or in another project. | Check the job ID. |
Asset not found |
The asset ID is wrong, deleted, or in another project. | Check the asset ID. |
Asset content not found |
The asset record exists but its stored file is missing. | Re-upload the asset. |
Schedule not found |
The schedule ID is wrong or in another project. | Check the schedule ID. |
Webhook not found |
The webhook ID is wrong or in another project. | Check the webhook ID. See I’m not receiving webhooks. |
Pinterest account not found |
The account_id is wrong, not in this workspace, or revoked. |
Confirm the account is connected. See My Pinterest account got disconnected. |
Project not found / Sandbox project not found |
The project (or sandbox) does not exist for this user. | Check the project, or create a sandbox first. |
API key not found |
The key ID is wrong or already revoked. | Check the key ID. |
Workspace not found |
The workspace behind the request cannot be resolved. | Confirm your key or session maps to a valid project. |
Tip: GET /v1/rate-meter also returns 404 (Pinterest account not found) when there is no connected account to query. Connect an account first.
409 Conflict
The request conflicts with existing state.
| Detail string | Cause | Fix |
|---|---|---|
Only failed pins can be retried |
You called retry on a pin that is not in the failed state. |
Only retry failed pins. Wait for auto-retries on queued/deferred pins. See My pin is stuck in queued. |
Account already exists for this email |
Signup or email change used an email that is already registered. | Sign in with that email, or use a different one. |
That email is no longer available. Request a new email change. |
The target email was taken between request and confirmation. | Start the email change again. |
You are already part of this organization. |
You accepted an invite to an org you already belong to. | No action needed. |
That user is already a member of this organization. |
You invited an existing member. | No action needed. |
An active invitation already exists for that email. |
A pending invite already exists. | Wait for it to be accepted, or revoke and re-invite. |
Organization production project is missing |
The organization has no production project. | Contact support to restore the production project. |
422 Unprocessable Entity
The request body failed validation. FastAPI returns an array of field errors under detail. Fix the field and retry.
| Field / rule | Cause | Fix |
|---|---|---|
account_id, board_id, title, idempotency_key required |
A required PinCreate field is missing. | Send all four required fields. idempotency_key is never auto-generated. |
Either image_url or asset_id must be provided |
Neither media source was set. | Provide exactly one of image_url or asset_id. |
Provide either image_url or asset_id, not both |
Both media sources were set. | Send exactly one. |
Provide either cover_image_url or cover_image_asset_id, not both |
Both cover fields were set. | Send at most one cover field (video pins only). |
dominant_color must be a 6-digit hex color |
The color is not a 6-digit hex value. | Send a hex color like #AABBCC (leading # optional). |
link_url must be <= 2048 characters |
The link URL is too long. | Shorten the URL to 2048 characters or fewer. |
cover_image_url must be <= 2048 characters |
The cover URL is too long. | Shorten to 2048 characters or fewer. |
title max 100 |
The title is over 100 characters. | Trim the title. |
description max 800 |
The description is over 800 characters. | Trim the description. |
alt_text max 500 |
The alt text is over 500 characters. | Trim the alt text. |
idempotency_key max 255 |
The key is over 255 characters. | Use a shorter key. |
Webhook secret (16-255 chars) required |
The webhook secret is missing or under 16 characters. | Provide a secret 16 to 255 characters long. See I’m not receiving webhooks. |
Webhook url invalid |
The webhook URL is not a valid HTTP(S) URL. | Send a valid URL. |
Owner role cannot be assigned by invitation |
You invited someone as owner. | Invite as admin, operator, or client. |
At least one terms value is required |
A related-terms lookup had no terms. | Supply at least one term. |
429 Too Many Requests
You hit a rate limit. All 429 responses include a Retry-After header. Wait that long, then retry.
| Detail string | Cause | Fix |
|---|---|---|
Too many sign-ups from this network. Please try again later. |
Too many signups from one IP. | Wait and retry, per Retry-After. |
| Password reset rate limit | Too many password reset requests. | Wait, per Retry-After. |
Please wait before requesting another verification email. |
Verification email requested too often. | Wait, per Retry-After. |
Please wait before requesting another email change. |
Email change requested too often. | Wait, per Retry-After. |
Note: pin-publish rate limiting from Pinterest is handled internally with automatic retries (the pin goes queued then deferred), not surfaced as a 429 on POST /v1/pins. See My pin is stuck in queued.
500 Internal Server Error
Something failed on our side or upstream at Pinterest. These responses include a request_id. Most are transient, so retry after a short wait; if it persists, contact support with the request_id.
| Detail string | Cause | Fix |
|---|---|---|
Internal server error (with request_id) |
An uncaught error. | Retry. If it persists, share the request_id with support. |
OAuth callback failed: ... |
Pinterest OAuth exchange failed upstream. | Retry the connect flow. See My Pinterest account got disconnected. |
Failed to fetch boards: ... |
Pinterest boards call failed upstream. | Retry shortly. |
Failed to fetch related terms: ... |
Pinterest related-terms call failed upstream. | Retry shortly. |
Failed to create board: ... |
Pinterest board create failed upstream. | Retry shortly. |
Failed to delete board: ... |
Pinterest board delete failed upstream. | Retry shortly. |
503 Service Unavailable
The service or a dependency is temporarily unavailable.
| Detail string | Cause | Fix |
|---|---|---|
| Enqueue failure on pin retry | The pin could not be queued; it is set back to failed. |
Retry the pin again shortly. See My pin failed. |
Admin API access is not configured |
The admin API is not configured on this deployment. | Applies to platform admins only. |
Pin failure error codes (not HTTP)
When a pin’s HTTP request succeeds but publishing later fails, the failure shows up on the pin object as error_code and error_message, not as an HTTP error. See My pin failed for the full list and what to do about each. Common values: rate_limited, token_expired, token_revoked, scope_missing, board_access_denied, transient_upstream, media_url_temporarily_unavailable, media_url_unreachable, resource_not_found, invalid_payload, publish_timeout, and a fallback api_error.
Next steps
- Troubleshooting — task-focused fixes by symptom.
- My pin failed — read a pin’s
error_code. - 402 quota_exceeded — quota, credits, and upgrades.