Salesforce Docs Portal

Troubleshooting


This guide covers common problems you may encounter when working with the External Client API and how to resolve them.

Table of Contents

Common REST API Issues

Below are typical issues encountered when making REST API requests, along with their likely causes and solutions.

400 Bad Request

Symptoms: The server rejects the request before processing it.

Common causes and solutions:

  • Malformed JSON body — Validate your request payload against the endpoint schema in the API Reference. Ensure quotes, commas, and braces are correct.
  • Missing required fields — Confirm that all required parameters are included in the request body or query string.
  • Incorrect Content-Type header — Set Content-Type: application/json for requests that include a JSON body.

401 Unauthorized

Symptoms: The request is rejected due to missing or invalid credentials.

Common causes and solutions:

  • Missing or expired token — Ensure a valid authentication token is included and has not expired. See Authentication Problems.
  • Malformed Authorization header — Verify the header format matches what the API expects.

403 Forbidden

Symptoms: The credentials are valid, but the operation is not permitted.

Common causes and solutions:

  • Insufficient permissions — Confirm the account or token has the required role or scope for the resource.
  • Accessing another site or resource — Verify you are targeting the correct site and that you have access to the requested resource.

404 Not Found

Symptoms: The requested resource does not exist.

Common causes and solutions:

  • Incorrect URL or path — Double-check the endpoint path, resource ID, and base URL.
  • Wrong API version — Confirm you are using the correct API version in the request path.

429 Too Many Requests

Symptoms: Requests are throttled due to rate limiting.

Common causes and solutions:

  • Exceeding rate limits — Implement exponential backoff and retry logic. Inspect any Retry-After response header to determine how long to wait.
  • Bursty traffic — Spread requests over time rather than sending them in large bursts.

500 / 503 Server Errors

Symptoms: The server encounters an error or is temporarily unavailable.

Common causes and solutions:

  • Transient server issue — Retry the request after a short delay with backoff.
  • Persistent failures — If the problem continues, capture the request ID and timestamp and contact support.

General Debugging Tips

  • Inspect the full response body and status code — error responses often include a descriptive message.
  • Log request and response headers to diagnose header-related problems.
  • Reproduce the request with a tool like curl or Postman to isolate client-side issues.

Authentication Problems

TBD — Content for this section is coming soon.

Studio API Issues

TBD — Content for this section is coming soon.