Skip to main content

Development

This document outlines the key guidelines and best practices that task developers should follow when implementing tasks in our system. Following these guidelines ensures consistency, reliability and security of the platform.

APIs Integration​

When integrating external APIs in your task:

  • Expose all relevant API functionality through the Task interface
  • Keep request/response models as closer to the original API
    • Avoid exposing original API execution specific details in the response. e.g. executionTime, status etc
  • Implement proper error handling

Ensure the task:

File Handling​

When working with files in tasks:

  • Always accept file inputs via URLs instead of base64 or binary representations.
  • FIle field names must end with url
  • Return only PA CDN file URLs as output
  • For external URLs in results, use the FILE_COPY task to store them in PA CDN first

Trust and Safety​

  • Tasks should fail when safety checks do not pass
  • When receiving user provided texts/prompts, tasks should make sure that the text does not violate our T&S guidelines using CHECK_TEXT task.

Error handling​

In case of failures tasks always should throw an instance of PicsartError class.

Keep in mind that any error thrown from the tasks may be (and probably will be) propagated to the end client even when wrapped in workflows. Therefore, make sure that errors include enough details to identify the failing task and root cause.

throw new PicArtError('<reason>', '<message>', '<http_status_code>');

reason​

Machine-readable identifier for the error

  • Format: lower_snake_case, ASCII only.
  • Stable: never change once shipped; add new codes instead.
  • Scope: codes should describe business/domain failures, not low-level implementation hiccups
  • Granularity: one cause → one code. Don’t overload a code for multiple causes.
    • Not too granular: don’t mirror every internal step or vendor detail.
  • Rule of thumb: pick the level of abstraction your clients care about, not the level your infrastructure exposes.
  • Examples:
    • ✅ image_safety_check_failed
    • ❌ openai_image_generation_invalid_image

message​

Human-readable details of the error

Audience: written for developers, depending on error reason, maybe shown to end user Tone: concise, actionable, no internals. Clarity: include enough detail to identify the root cause (e.g. model name, reason, upstream error) without oversharing sensitive info. Examples:

  • ✅ gpt-image-1 failed with invalid_aspect_ratio reason
  • ❌ Image generation failed
  • ❌ Something went wrong!

status code​

  • external api failures: 503
  • safety check failures: 422