PingRepDocs

Reference

Error Codes

HTTP status codes, error response formats, and troubleshooting guidance for the PingRep API.

Error response format

All PingRep API errors return a JSON body with a detail field. The format of detail depends on the error type.

Simple errors

Most errors return a string describing what went wrong.

Validation errors

Requests that fail input validation return an array of field-level errors with the location, message, and type of each issue.

Validation error fields:

locarrayRequired

Path to the field that caused the error. First element is the location (body, query, path) and the rest is the field path.

msgstringRequired

Human-readable description of the validation failure.

typestringRequired

Machine-readable error type for programmatic handling.

HTTP status codes

CodeNameDescription
400Bad RequestThe request body or parameters are malformed. Check the detail field for specifics.
401UnauthorizedMissing or invalid authentication. Verify your API key or JWT token.
403ForbiddenYou are authenticated but lack permission for this action. Check your scopes or role.
404Not FoundThe requested resource does not exist. Verify the ID or slug in your request path.
409ConflictA resource with the same unique identifier already exists. Common with duplicate emails or slugs.
410GoneThe resource existed but has expired or been permanently removed. Common with magic link tokens.
422Unprocessable EntityThe request is syntactically valid but semantically incorrect. Check field values and constraints.
429Too Many RequestsYou hit a rate limit. See Rate Limits for details.
500Internal Server ErrorSomething went wrong on our side. Retry after a brief delay. If it persists, contact support.

Common errors and solutions

401 Unauthorized

Causes:

  • Missing Authorization header
  • Expired JWT token
  • Revoked API key

Fix: Include a valid Authorization: Bearer <token> header. If using a JWT, check the expiration time and refresh if needed. If using an API key, verify it has not been revoked.

403 Forbidden

Causes:

  • API key missing the required scope for this endpoint
  • User role does not permit this action in the organization
  • Attempting to modify another user's resource

Fix: Check your API key scopes with GET /api/v1/api-keys/scopes. For organization actions, verify your role permits the operation.

409 Conflict

Causes:

  • Creating a profile with a slug that is already taken
  • Inviting a member who is already in the organization

Fix: Use a different unique identifier or check for existing resources before creating.

410 Gone

Causes:

  • Magic link token used after its expiration window
  • One-time token already consumed

Fix: Request a new magic link or token. These are single-use and time-limited by design.

429 Too Many Requests

Fix: Read the X-RateLimit-Reset header and wait until the window resets. See Rate Limits for retry strategies and per-tier allowances.

Error handling best practices

  1. Always check the status code first. Branch your logic on the HTTP status before parsing the body.
  2. Parse validation errors programmatically. Use the loc field to map errors back to specific form fields.
  3. Log the full response. Include the status code, headers, and body in your error logs for debugging.
  4. Do not retry 4xx errors blindly. Client errors (400, 401, 403, 404, 409, 422) require you to fix the request before retrying. Only 429 and 5xx errors benefit from retries.

Need help?

If you encounter persistent 500 errors, contact support@pingrep.com with the request details and timestamps so we can investigate.