Guides

Troubleshooting

Navigate through common issues with Picsart APIs using this practical troubleshooting guide to quickly resolve any challenges.

Suggest Edits

Common Issues

  • Double-check that all mandatory parameters have been provided
  • Avoid providing image, image_url, and image_id simultaneously. Only one of these should be included as input.

Correctly Structuring API Request Bodies

When interacting with endpoints, it's crucial to format your request body correctly to avoid errors. If an endpoint expects a JSON object and your request body is not formatted as such, you're likely to encounter a 400 Bad Request response.

Similarly, neglecting to include required parameters or misusing parameter types can lead to a 422 Unprocessable Entity response. For instance, receiving this error might occur if a parameter is given as an array when the endpoint expects a string or the parameter value should be in the range of 0-100 but 102 or negative numbers are provided. Always consult the endpoint's reference documentation to ensure correct parameter types are used and all necessary parameters are included.

It's important to note that not all requests will require a body. However, for those that do, understanding whether the endpoint expects an application/json body, necessitating the body to be a JSON object, or a multipart/form-data body is essential for successful API interaction. Each type of request body serves different purposes and must be used accordingly to meet the API's requirements.

Minimize Simultaneous Requests

To steer clear of surpassing secondary rate limits, it's recommended to sequence your requests rather than executing them in parallel. Establishing a queuing mechanism for managing requests can facilitate this approach.

Be aware that the API provides the X-Picsart-RateLimit-Available header, indicating the allowable number of calls until the reset time marked by X-Picsart-RateLimit-Reset-Time. Additionally, note the distinct limit of 300 requests per second as part of the spike arrest mechanism.

To align with these constraints, consider strategies for distributing your request load evenly. This may involve throttling your requests to stay within the per-second limit and scheduling requests to optimize usage of your available rate limit window, thus ensuring smooth and uninterrupted API interaction.

Manage rate limit errors effectively

Upon encountering a rate limit error, it's crucial to pause your request attempts in alignment with these recommendations:

  • If your request is met with a rate limit error and the x-picsart-ratelimit-reset-time header is provided, wait to make another request until the time specified by this header has been reached. The X-Picsart-RateLimit-Reset-Time indicates the reset time in UTC epoch milliseconds.
  • In cases where the X-Picsart-RateLimit-Available header indicates 0, hold off on any further requests until the epoch time indicated by the X-Picsart-RateLimit-Reset-Time header has been reached. This header reflects the time in UTC epoch milliseconds.
  • If neither condition applies, it's advisable to wait at least one minute before attempting your request again. Should you continue to encounter rate limit issues due to a secondary restriction, increase the wait time exponentially with each retry and consider throwing an error after several failed attempts.

Persisting in sending requests while facing rate limitations can lead to the suspension of your integration.

Avoid manually dissecting URLs

It's common for API responses to include URL values within the response body's fields. Attempting to dissect these URLs or anticipate the configuration of future URLs can jeopardize the stability of your integration, especially if there are future changes to the URL structure by the API provider. Rather than parsing URLs, seek out specific fields that carry the data you require. For example, when an endpoint for generating an image returns a url field with a value like https://cdn.picsart.io/ef72b5f2-e3fc-47b8-8eba-b63f92812637.png?type=PNG&to=max&r=0, reference the URL value directly instead of stripping off the parameters or providing other values.

Avoid overlooking errors

Repeatedly encountering 4xx and 5xx error codes should not be disregarded. It's important to verify that your interactions with the API are appropriate. For instance, supplying a numeric value when an endpoint expects a string can trigger a validation error. Likewise, trying to reach an endpoint that's unauthorized or does not exist will lead to a 4xx error.

Some of the special codes to keep an eye for are

  • 404 - when the requested endpoint does not exist. Common reasons include:
    • Typographical errors in the URL
    • Incorrect endpoint paths
    • Including unintended double slashes in the URL, such as /tools/1.0//removebg
  • 406 - for when the client doesn't specify the accept: application/json header to let our services know that the JSON response will be properly handled
  • 413 - for when the input file is too big
  • 422 - for when the input parameters don't pass validations (don't meet requirements that are defined in the reference documentation)

Choosing to disregard ongoing validation errors could lead to your application being suspended for misuse.

Detecting Bot Activity

To enhance the security of our API services, we have implemented checks and guards to detect bot activity. When such activity is identified, we return a 403 status code with the following response:

{
    "message": "Bot Activity",
    "detail": "Bot activity detected. If you are a developer, please visit our troubleshooting page at https://docs.picsart.io/docs/creative-apis-troubleshooting for more information. Unauthorized activity is prohibited."
}

This response aims to deter unauthorized access while providing legitimate developers with guidance to rectify any issues. If you encounter this issue, please reach out to our support team for assistance in bypassing it for legitimate access to Picsart Creative APIs services.

Handling Unspecified Errors

For errors not covered in this guide, consult the API's provided error message for insights into the issue, often including hints and links to pertinent documentation.

In cases of unforeseen failures, checking Status Page can help determine if there are any ongoing incidents impacting API functionality.

📘

If you cannot to find a solution, please contact our support team.

Reporting issues

  • Capture the value of the X-Picsart-Correlation-Id response header and include it in your report.
  • Record the response body if it is an error response. Any HTTP status codes equal to or greater than 400 are considered error responses.
  • Provide as much detail as possible about the issue you are experiencing, including screenshots or screen recordings, to help our support team resolve the problem quickly.
  • Contact your account team or dev support engineer with the aforementioned information for future assistance.

Expand your knowledge:

Updated 6 months ago